Documentation for Build v2.08
Table of Contents

Switches

Build supports a number of command line switches to control its default assumptions.


  • switch -allobj   Ensures that all object files are added to a library.
  • switch -CFPATH   Identifies where the D config file has been installed.
  • switch -cleanup   Ensures that all working files created during the run are removed.
  • switch -DCPATH    Identifies where the compiler has been installed.
  • switch -dll   Forces a DLL library to be created.
  • switch -full   Causes all source files, except ignored modules, to be compiled.
  • switch -gui   Forces a GUI application to be created.
  • switch -help   Displays the full text of the Usage information.
  • switch -info    Displays the version and path of the build application
  • switch -lib   Forces the object files to be placed in a library.
  • switch -LIBOPT   Allows commandline options to be passed to the librarian.
  • switch -LIBPATH   Used to add a list of search paths for library files.
  • switch -link   Forces the linker to be called instead of the librarian.
  • switch -M   Identifies a module or a package to notice (not ignore)
  • switch -names   Displays the names of the files used in building the target.
  • switch -noautoimport   Prevents source file paths from being added to the list of Import Roots
  • switch -nodef   Prevent a Module Definition File being created.
  • switch -nolib   Ensures that the object files are not used to form a library.
  • switch -nolink    Ensures that the linker is not called.
  • switch -obj    Shorthand for using both -nolink and -nolib switches.
  • switch -od   Nominates the temporary file directory.
  • switch -R   Determines if the compiler tools use a response file or not.
  • switch -RDF    Defines a file to override the default Rule Definition File
  • switch -silent   Prevents unnecessary messages being displayed.
  • switch -T   Identifies the target name to build.
  • switch -test   Does a test run only. No compiling, linking or library work is done.
  • switch -V    Set verbose mode on for just build and not for the compiler
  • switch -v    Set verbose mode on for both build and for the compiler
  • switch -X   Identifies a module or package to ignore

    Documentation for Build v2.08
    Table of Contents

    [switch]
    -allobj

    Ensures that all object files are added to a library.

    Category: Switches

    Normally, build will only create a library using the object files that are in the same directory as the new library. You would use this switch if you wanted all object files created by this build session to be included in the library.

    See Also: -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -CFPATH

    Identifies where the D config file has been installed.

    Category: Switches

    Normally, build looks in the same place that the compiler is installed in, but if you need to use a different configuration path from that, you would use this switch to tell build where it is.

    Example:

    -CFPATHc:\myproject\configs
    

    See Also: -allobj, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -cleanup

    Ensures that all working files created during the run are removed.

    Category: Switches

    Normally, build does not delete any object files or working files when it finishes a session. You can use this switch to have build clean up after itself. This will remove all object files created in this run, plus any .rsp, .lsp, .bak, .map, .lst, .def files.

    Note: This can also be supplied as -clean as an alias.

    See Also: -allobj, -CFPATH, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -DCPATH

    Identifies where the compiler has been installed.

    Category: Switches

    Normally, build scans the PATH environment symbol to find where the D compiler is located. However, if you need to use the compiler from a different location, you would use this switch to tell build where it is.

    Note: If you use this switch, and the current CFPATH value is identical to the current DCPATH value, then this switch will change both to the new value. The assumption is that the configuration file is in the same directory as the compiler. If this is not the case, you will also need to use the -CFPATH switch.

    Example:

    -DCPATHc:\old\dmd\bin
    

    See Also: -allobj, -CFPATH, -cleanup, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -dll

    Forces a DLL library to be created.

    Category: Switches

    Note: This only applies to Windows environment.

    Normally, if build finds a DllMain() function it automatically creates a DLL library. However, if you need to force a DLL library, you would use this switch.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -full

    Causes all source files, except ignored modules, to be compiled.

    Category: Switches

    Normally, build only compiles a source file if it's object file is out of date or missing. This switch forces all source files to be recompiled, even if not strictly required.

    Note: Modules in the ignore list are still ignored though.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -gui

    Forces a GUI application to be created.

    Category: Switches

    Note: This only applies to Windows environment.

    Normally, if build finds a WinMain() function it automatically creates a GUI application. However, if you need to force a GUI application, you would use this switch.

    This switch can also be used to specify which version of Windows to build the application for. To do this, it takes the format of -gui:X.Y where X.Y is the Windows version number. Use 4.0 for Windows NT, 2000, and ME, and 5.0 for Windows XP.

    By default, build uses the version of Windows it is running under.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -help

    Displays the full text of the Usage information.

    Category: Switches

    This has the aliases of "-h" and "-?"

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -info

    Displays the version and path of the build application

    Category: Switches

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -lib

    Forces the object files to be placed in a library.

    Category: Switches

    Normally, if build finds a main() or WinMain() function, it tries to create an application by calling the linker. But if you use this switch, the librarian is called instead of the linker.

    You would typically do this if you wanted to create a library that stores your 'main' function in it, in which case you'd also use the -nolink switch.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -LIBOPT

    Allows commandline options to be passed to the librarian.

    Category: Switches

    Example:

    (Set the page size to 32Kb)
    -LIBOPT-p32
    

    (Embedded spaces enclosed in quotes.) "-LIBOPT -l -i"

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -LIBPATH

    Used to add a list of search paths for library files.

    Category: Switches

    This might be used when you don't want to permanently update the standard search paths. Example:

    -LIBPATH=c:\mylibs;d:\3rdparty;c:\lib\debuglibs
    

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -link

    Forces the linker to be called instead of the librarian.

    Category: Switches

    Normally, if build does not find a main() or WinMain() function in the source files, it creates a library to contain the object files. But when this switch is used, build will attempt to create an application by calling the linker rather than the librarian.

    You would typically use this if the main() function was being supplied from an existing library file rather than one you your source files.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -M

    Identifies a module or a package to notice (not ignore)

    Category: Switches

    You would use this to name any module that is not part of the target's dependancies, or is one of the ignored modules.

    You can use this switch to recompile phobos.

    Example (notice the Phobos package):

    -Mphobos
    

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -names

    Displays the names of the files used in building the target.

    Category: Switches

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -noautoimport

    Prevents source file paths from being added to the list of Import Roots

    Category: Switches

    By default, for each source file that imports a module, it's path is added to the list of paths that will be searched for module source files. If you do not wish that behaviour, you will need to use this switch. In that case, the compiler will only search the paths specified in the compiler's configuration file, the current directory, and any explicitly added paths on the command line.

    Example:

    build myApp -noautoimport
    

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -nodef

    Prevent a Module Definition File being created.

    Category: Switches

    Normally, the utility will automatically create a Module Definition File for the linker. This will typically contain the EXETYPE command and any other commands as specified in any pragma(/build_def) statements found in the source files. If you specify this switch, you will have to provide your own Module Definition File or its equivalent on the command line.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -nolib

    Ensures that the object files are not used to form a library.

    Category: Switches

    Normally, if build does not find a main() or WinMain() function, it calls the librarian to create a library for all your object files. But if you use this switch, the librarian is not called.

    Typically, you would do this if you just wanted to create one or more object files and do nothing else.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -nolink

    Ensures that the linker is not called.

    Category: Switches

    Normally, if build finds a main() or WinMain() function, it tries to create an application by calling the linker. If you use this switch however, the linker will not be called.

    You would typically do this if you wanted to create a library that stores your 'main' function in it, in which case you'd also use the -lib switch. But you could just create a set of object files without linking them with this switch.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -obj

    Shorthand for using both -nolink and -nolib switches.

    Category: Switches

    This is literally the same has if you had placed both -nolink and -nolib on the command line. As this is a common way to just compile modules to get the object files for them, without doing anything else, a neat shorthand is available.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -od, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -od

    Nominates the temporary file directory.

    Category: Switches

    By default, the utility creates any work files in the same directory as the target file. You can use this switch to nominate an alternative location for these files. The directory is created if it doesn't exist.

    For the DigitalMars compiler, this also specifies the top-level location where object files are created. By default, object files are created in the same directory as the corresponding source file.

    Example:

    -odC:\temp\workarea
    

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -R, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -R

    Determines if the compiler tools use a response file or not.

    Category: Switches

    For DigitalMars tools in the Windows environment, a response file is the default, but for other tools and other operating systems the default is to use command line arguments.

    The switch has three formats:
    -Ry to use a response file
    -Rn to use command line arguments
    -R to reverse the current setting.

    The use of a response file is only really needed when the command line arguments are going to be more than the operating system can handle on a single command line. However, it is always a safe option, so if in doubt you may as well use it.

    A response file contains all the arguments that would have gone on the command line. They are arranged as one argument per line.

    Not all tools respect the response file idea however the Windows based DigitalMars tools do understand it.

    Without a response file the compiler might be invoked thus:

    dmd -op -release appmain.d somemod.obj -IC:\DLibs
    
    But with a response file, these arguments are first written out to a text file (the response file) and the compiler is invoked :
    dmd @appmain.rsp
    
    The appmain.rsp would contain the lines :
    -op
    -release
    appmain.d
    somemod.obj
    -IC:\DLibs
    

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -RDF, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -RDF

    Defines a file to override the default Rule Definition File

    Category: Switches

    The default file is called "default.rdf". If you need to provide an alternate file, you can use this switch.

    Example:

    -RDFmyrules.xyz
    

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -silent, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -silent

    Prevents unnecessary messages being displayed.

    Category: Switches

    Some messages are just informational and under some circumstances they can interfer with reading the output.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -T, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -T

    Identifies the target name to build.

    Category: Switches

    Normally, build derives the target name from the first file name on the command line, or from the pragma(target) if present. If however, you wish to override that, use this switch.

    Note: This switch allows the use of a special token, {Target}, which is replaced by the default target name. You can use to create a generic Response File that can be used for building any application.

    Example

    -Ttestapp
    

    -Ttest_(Target} # Generate a name based on the default name.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -test, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -test

    Does a test run only. No compiling, linking or library work is done.

    Category: Switches

    This will display the command lines instead of running them. It can be used to see what would happen without actually building anything.

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -V, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -V

    Set verbose mode on for just build and not for the compiler

    Category: Switches

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -v, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -v

    Set verbose mode on for both build and for the compiler

    Category: Switches

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -X


    Documentation for Build v2.08
    Table of Contents

    [switch]
    -X

    Identifies a module or package to ignore

    Category: Switches

    Normally, build assumes that all imported modules are available to be recompiled if required. You would use this switch if you explictly did not want build to recompile a module.

    Note: The Phobos package of modules is automatically ignored. This means that build does not try to recompile phobos.

    Example - ignore the 'parser' module (or package)

    -Xparser
    

    See Also: -allobj, -CFPATH, -cleanup, -DCPATH, -dll, -full, -gui, -help, -info, -lib, -LIBOPT, -LIBPATH, -link, -M, -names, -noautoimport, -nodef, -nolib, -nolink, -obj, -od, -R, -RDF, -silent, -T, -test, -V, -v