The utility's configuration file is used to specify your default options
for the utility. The file is called
build.cfg. You can have from zero
to four configuration files because the
Bud utility looks in each
of four places for a configuration file, and it uses each one that it finds.
It looks in the folder that
Bud is installed, then in a user defined
alternative path (defined by -BCFPATH switch), then in the folder
that the compiler is installed, and finally in the current folder.
Note: The alternative location is optional. It can be specified in
an environment switch called BCFPATH or in a command line switch
of the same name, -BCFPATH.
The configuration file consists of one or more command lines.
Each command line is specified in a single text line, but you can have any
number of command lines in the configuration file.
The command lines take the form of
<COMMAND>=<VALUE>
Supported Commands
The commands currently supported are ...
CMDLINE
You can specify all command line switch values with this configuration
option. You can also specify multiple switches on the same option line.
CMDLINE=-inline -w
LIBCMD
This specifies the location and program name for the librarian application
you want to invoke when creating libraries.
LIBCMD=D:\Applications\dm\bin\lib.exe
LINKCMD
This specifies the location and program name for the linker application
you want to invoke when creating executables.
LINKCMD=ld
LINKSWITCH
This specifies the default set of switches passed to the linker. If this
command is not in the configuration file, the built-in default is "/noi"
when using the DMD linker.
LINKSWITCH=/info
FINAL
This specifies a command that will run after the target has been
successfully created. There can be any number of
FINAL commands
in a configuration file; they are all executed, and in the order presented.
You can place special tokens in the
FINAL command line and these will
be replaced just before running the command line.
| Token | Replacement |
| {Target} | The full path and name of the target file created |
| {TargetPath} | The path of the target file created |
| {TargetBase} | The name of the target file created |
FINAL="c:\program files\upx202w\upx" --best -q {Target} >nul
INIT:
This specifies an internal string value. The format is actually
INIT:stringname where
stringname identifies the specific
internal string to set.
INIT:MapSwitch = -M
The identifiers for the settable strings are detailed below.
ExeExtension
The file extension for executable files. Example: "exe"
LibExtension
The file extension for library files.Example: "lib"
ObjExtension
The file extension for object files.Example: "obj"
ShrLibExtension
The file extension for shared libraries files.Example: "dll"
SrcExtension
The file extension for D source files.Example: "d"
MacroExtension
The file extension for macro files.Example: "mac"
DdocExtension
The file extension for D Documentation files.Example: "ddoc"
CompilerExe
The file name of the compiler.Example: "dmd.exe"
CompileOnly
The switch that is passed to the compiler to tell
it not to link, just compile the files instead.Example: "-c"
LinkerExe
The file name of the linker.Example: "link.exe"
ConfigFile
The name of the compiler's configuration file. Example: "sc.ini"
CompilerPath
If the compiler is not in the standard search PATH,
this specifies the location of the compiler. Example: "F:\dmd\bin"
ConfigPath
This will specify where to look for the compiler's
configuration file. It overrrides the default
places to look for it. Example: "D:\configarea"
LinkerPath
If not overriden by any LINKCMD=
option found in the compiler's configuration file,
this specifies the location of the linker.
Example: "F:\dm\bin"
If this empty and there is no LINKCMD= found,
the linker is assumed to be in the same place as the
compiler.
LinkerDefs
The default set of switches for the linker. These are
applied to every link run. Example: "/noi /map"
LibPaths
The default set of paths used by the linker to
scan for library files. Example: "C:\mylibs;c:\dfl"
ConfigSep
The delimiter used to separate paths in the
LibPaths list. Example: ";"
Librarian
The name of the librarian tool. Example: "lib.exe "
LibrarianOpts
The default switches that are always passed to
the librarian tool. Example: "-c -p256"
VersionSwitch
The switch that sets a version symbol for the
compiler. Example: "-version"
DebugSwitch
The switch that sets a debug symbol for the
compiler. Example: "-debug"
CompilerDefs
The default switches that are always passed to
the compiler. Example: "-op"
Note that in the DigitalMars environment if
you don't specify any CompilerDefs, "-op" is
assumed.
OutFileSwitch
The switch tells Bud
where to create the executable file. Example: "-of"
ImportPath
This is the switch for the compiler to tell it where
to search for imported modules. Example: "-I"
LinkLibSwitch
This is the switch for the linker to tell it
a library to use. Example: "-l"
LibPathSwitch
This is the switch for the linker to tell it
where to search for the libraries. Example: "-L"
MapSwitch
This is the switch for the linker to tell it
to create a map file. Note that the DigitalMars
linker does not have a switch for this function.
Example: "-M"
SymInfoSwitch
This is the switch for the linker to tell it
to insert symbolic debugging information into
the executable.Example: "/co"
BuildImportPath
This is the switch for Bud to tell it
a path to scan for imported modules. Example: "-I"
ImportPathDelim
This is the switch for Bud to tell it
which character is used to delimit paths on
a BuildImportPath list. Example: ";"
OutputPath
This is the switch for Bud to tell it
the path to use for all temporary output files. Example: "-od"
RunSwitch
This is the switch for Bud to tell it
to run the application once it successfully
compiles. Example: "-exec"
LibrarianPath
This is the default path where build will run
the librarian tool from. It will be overridden
by a 'LIBCMD=' in the configuration file or
on the commandline. Example: "c:\tools\"
ResponseExt
This is the file extension that Bud will use
for its response files. Example: "brf"
DefResponseFile
This is the name of the Bud default
response file. Example: "build.brf"
RDFName
This is the name of the Bud default
Rules Definition File. Example: "default.rdf"
DefMacroDefFile
This is the name of the Bud default
Macro Definition File. Example: "build.mdf"
LinkerStdOut
This is the commandline option given to the linker
when the Bud commandline has the "-silent"
switch. Example: ">nul"
IgnoredModules
This is a comma delimited list of modules or packages
to ignore. Bud will not scan these modules and
packages for dependancies. Example: "std,dfl,dui"
If none is specified by this configuration item then
'phobos' is assumed.
AssumedLibs
This is a comma delimited list of libraries that
are passed to the linker.
Example: "dfl,mt"
If the application being compiled has a WinMain
function or is otherwise identified as a Windows
application then the following are automatically
passed to the linker.
- gdi32.lib
- advapi32.lib
- COMCTL32.LIB
- comdlg32.lib
- CTL3D32.LIB
- kernel32.lib
- ODBC32.LIB
- ole32.lib
- OLEAUT32.LIB
- shell32.lib
- user32.lib
- uuid.lib
- winmm.lib
- winspool.lib
- wsock32.lib
If the application is being compiled in a Unix
environment then the following are automatically
passed to the linker.
PathId
The name of the environment symbol used by Bud
when scanning for executables. Example: "PATH"
HomePathId
The name of the environment symbol used by Bud
when scanning for configuration file. Example: "HOME"
EtcPath
The name of an alternative path used by Bud
when scanning for configuration file. Example: "c:\etc\"
GenDebugInfo
The switch that tells Bud and the compiler
to insert debugging information into the object
files. Example: "-g"
ModOutPrefix
If the Bud switch "-modules" was
used, this defines the string which Bud will
begin the Modules List output file with.
Example: "MODULES = \n"
ModOutSuffix
If the Bud switch "-modules" was
used, this defines the string which Bud will
end the Modules List output file with.
Example: ""
ModOutBody
If the Bud switch "-modules" was
used, this defines the string which Bud will
use as a template for each module being listed.
Example: " $(MODULE {mod})"
Note that {mod} will be replaced with the module's
name and {src} will be replaced with the source
file's name.
ModOutDelim
If the Bud switch "-modules" was
used, this defines the string which Bud will
insert in between each listed module.
Example: "\n"
ModOutFile
If the Bud switch "-modules" was
used, this defines the output file's suffix. This
is only used if the "-modules" switch
did not specify an exact file name to use. In which
case the Target name is used as a prefix and this
string as the suffix.
Example: "_modules.ddoc "
ArgDelim
This value will be the delimiter for file groups
on the linker command line. A file group is a set
of like filetypes such as objects or libraries
Example: ", "
ArgFileDelim
This value will be the delimiter for files within
a file group on the linker command line. A file group is a set
of like filetypes such as objects or libraries
Example: "+ "
PostSwitches
If 'yes' this causes linker switches to go after
all the other command line entries, otherwise the
switches precede them.
Example: "Yes "
AppendLinkSwitches
If 'yes' this causes linker switches to be
appended to the last item on the command line
otherwise there will be a gap between the last
item and the first switch.
Example: "Yes "
Example:
INIT:MacroExtension = bmc
INIT:LinkerPath = /u2/qwerty/
INIT:AssumedLibs = c,kde,mgui
Default Values for Configuration Items
| INIT: item | DigitalMars-Windows | GDC-Windows | DigitalMars-Unix | GDC-Unix |
| ExeExtension | exe | exe | | |
| LibExtension | lib | lib | a | a |
| ObjExtension | obj | obj | o | o |
| ShrLibExtension | dll | dll | s | s |
| SrcExtension | d | d | d | d |
| MacroExtension | mac | mac | mac | mac |
| DdocExtension | ddoc | ddoc | ddoc | ddoc |
| CompilerExe | dmd.exe | gdc.exe | dmd | gdc |
| CompileOnly | -c | -c | -c | -c |
| LinkerExe | link.exe | gdc.exe | gcc | gdmd |
| ConfigFile | sc.ini | | dmd.conf | |
| ConfigPath | | | | |
| CompilerPath | | | | |
| LinkerPath | | | | |
| LinkerDefs | /noi/map | | | |
| LibPaths | | | | |
| ConfigSep | ; | ; | : | : |
| Librarian | lib.exe | ar.exe | ar | ar |
| LibrarianOpts | -c -p256 | -c | -r | -r |
| VersionSwitch | -version | -fversion | -version | -fversion |
| DebugSwitch | -debug | -fdebug | -debug | -fdebug |
| OutFileSwitch | -of | "-o " | -of | "-o " |
| ImportPath | -I | "-I " | -I | "-I " |
| LinkLibSwitch | -l | -l | -l | -l-L |
| LibPathSwitch | -L | -L | -L | -L |
| MapSwitch | -M | -M | -M | -M |
| SymInfoSwitch | /co | /co | /co | /co |
| BuildImportPath | -I | -I | -I | -I |
| ImportPathDelim | ; | ; | ; | ; |
| OutputPath | -od | -od | -od | -od |
| RunSwitch | -exec | -exec | -exec | -exec |
| LibrarianPath | | | | |
| ResponseExt | brf | brf | brf | brf |
| DefResponseFile | build.brf | build.brf | build.brf | build.brf |
| RDFName | default.rdf | default.rdf | default.rdf | default.rdf |
| DefMacroDefFile | build.mdf | build.mdf | build.mdf | build.mdf |
| LinkerStdOut | >nul | >nul | >/dev/null | >/dev/null |
| IgnoredModules | | | | |
| AssumedLibs | | | | |
| PathId | PATH | PATH | PATH | PATH |
| ModOutPrefix | "MODULES = \n" | "MODULES = \n" | "MODULES = \n" | "MODULES = \n" |
| ModOutSuffix | | | | |
| ModOutBody | " $(MODULE {mod})\n" | " $(MODULE {mod})\n" | " $(MODULE {mod})\n" | " $(MODULE {mod})\n" |
| ModOutDelim | | | | |
| ModOutFile | _modules.ddoc | _modules.ddoc | _modules.ddoc | _modules.ddoc |
| GenDebugInfo | -g | -g | -g | -g |
| CompilerDefs | | | -version=Posix | -fversion=Posix |
| HomePathId | HOME | HOME | HOME | HOME |
| EtcPath | | | /etc/ | /etc/ |
| ArgDelim | , | | | |
| ArgFileDelim | + | | | |
| PostSwitches | Yes | No | No | No |
| AppendLinkSwitches | Yes | No | No | No |
Environment Symbol Substitution
Before each configuration file option line is processed, it is first checked
for any references to Environment symbols. Each reference is replaced by
the value of that symbol. References take the form
%<SYMNAME>%
There are three special symbols:
@D is replaced by the compiler's
path,
@P is replaced by the compiler's configuration file's path,
and
%% is replaced by a single
% character and can be used
to avoid an unwanted environment symbol substitution.
Example: Assuming you had set BUILDOPTS=-w -g
CMDLINE=%BUILDOPTS% # Allow switches to be passed via enviroment symbol.
would mean that "-w -g" would be automatically placed on the utility's
commandline whenever you ran it.
Groups
It is possible to specify groups of configuration options that are only
applied if explictly nominated on the command line. A group starts with
a line in the format
[<groupname>] where
groupname can be any
text that doesn't include spaces. A group ends on the last line before the
next group in the file.
Example: a Group
[dbg] # To produce a debug edition of an application.
CMDLINE=-unittest
CMDLINE=--release
CMDLINE=--inline
CMDLINE=-g
CMDLINE=-w
CMDLINE=-full
CMDLINE=-T{Target}_{Group}
All the options lines before the first group are known as the default
options because these are always applied. To apply the options in a group
you need to specify which group(s) you want on the command line, or via
a . The group name is prepended with a plus sign on
the command line. To apply the 'debug' group in the above example, you
place on the command line
+dbg
There are few optional predefined group names that are used when building
for specific environments.
[Windows]
# items that only apply when building in Windows.
[Posix]
# items that only apply when building in Posix (unix).
[darwin]
# items that only apply when building in Macintosh Darwin (OS X).
[DigitalMars]
# items that only apply when building with DigitalMars tools.
[GNU]
# items that only apply when building with GNU tools.
[Windows:DigitalMars]
# items that only apply when building with DigitalMars tools in Windows.
[Windows:GNU]
# items that only apply when building with GNU tools in Windows.
[Posix:DigitalMars]
# items that only apply when building with DigitalMars tools in Posix.
[Posix:GNU]
# items that only apply when building with GNU tools in Posix.
These groups are automatically used when building in the appropriate
enviroments and do not explicitly have to be mentioned on the command line.
Comments
You may place comments in a configuration file. A comment starts
with a
# character and extends to the end of the line.
Blank lines are ignored.
Example:
build myapp.d +production
where if a group called '[production]' is contained in any configuration
file, the options in that group are used.
Example: contents of [production]
# This creates a production (release) edition of the app.
[production]
CMDLINE=-T{Target}_{Group} # Set the name of the executable.
CMDLINE=-release # Don't generate runtime checks.
CMDLINE=-full # Force compilation of all files.
CMDLINE=-cleanup # remove work files when completed
CMDLINE=-inline # Allow inlining to occur
CMDLINE=--debug* # Turn off any debug switches
CMDLINE=--unittest # Turn off any unittest switches
CMDLINE=--w # Turn off warnings
CMDLINE=--g # Turn off embedded debug symbolic info.
You can any number of configuration file group references on a command line. They
are processed in the order they appear.