responsefile

README

responsefile

A tiny library to support response files, newline-separated plaintext files which hold lists of arguments.

Response files are commonly used on systems with low argument length limits, such as Windows.

Supported by GCC, Windows, the Go toolchain, and many others.

Documentation

Overview

Package responsefile provides support for response files, newline-separated plaintext files which hold lists of arguments.

Response files are commonly used on systems with low argument length limits, such as Windows. They are supported by programs like GCC, Go's compiler and linker, Windows toolchains, and the ninja build system.

Response files have no formal specification or grammar, but they are commonly identified by an argument starting with '@' followed by a path to a file containing newline-separated arguments. Since arguments may themselves contain newlines, newline and backslash characters are escaped with backslashes.

Nested response files are also supported, although not all programs support reading them.

Useful links: * https://gcc.gnu.org/wiki/Response_Files * https://learn.microsoft.com/en-us/windows/win32/midl/response-files * https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/2023-0/use-response-files.html

TODO: some implementations support quoting. TODO: some implementations support '#' comments.

Index

• func Expand(args []string, opts ExpandOptions) ([]string, error)
• func Shorten(args []string, opts ShortenOptions) (_ []string, cleanup func(), _ error)
• type ExpandOptions
• type ShortenOptions

Functions

func Expand

func Expand(args []string, opts ExpandOptions) ([]string, error)

Expand produces an argument list with any response files replaced with their inner arguments.

The args slice may be returned directly if no response files were found; otherwise, a new slice is returned.

func Shorten

func Shorten(args []string, opts ShortenOptions) (_ []string, cleanup func(), _ error)

Shorten produces an argument list which may use response files if args is too long.

If no error is reported, a cleanup func is returned, which must be called to avoid leaving temporary files behind.

The args slice may be returned directly if no response files were needed; otherwise, a new slice is returned.

Types

type ExpandOptions

type ExpandOptions struct {
}

ExpandOptions holds parameters for Expand.

type ShortenOptions

type ShortenOptions struct {
	// ArgLengthLimit is the number of bytes which can be passed directly
	// as arguments without using response files.
	// The zero value implies the default of 30KiB,
	// as Windows is known to have a limit of around 32KiB.
	//
	// A negative value can be used to always create response files.
	ArgLengthLimit int
}

ShortenOptions holds parameters for Shorten.