AlliedModders Wiki - User contributions [en]

AMBuild API

2023-11-10T03:47:26Z

BAILOPAN: /* Protobufs */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]
* See [[#Protoc as a Tool]]

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
<li>''StaticLibrary'': Helper to create a C++ static library out of .proto files.
</ul>

==Invoking protoc==
The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==C++ Protobuf Libraries==
To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

==Protoc as a Tool==

You can also embed generated protobufs directly into BinaryBuilders. For example:

<python>
prog = cxx.Program('prog')
protos = builder.tools.Protoc(sources = ['myproto.proto'])
prog.custom += [protos]
</python>

This compiles the pb.cc files in the same context as the binary. The <tt>Protoc()</tt> constructor takes two arguments:
<ul>
<li>''protoc'': Optional detected protoc. If omitted, <tt>DetectProtoc()</tt> is called automatically.</li>
<li>''sources'': Optional list of protobuf source files.</li>
</ul>

The return value is a <tt>ProtocJob</tt>, which has the attributes ''protoc'' and ''sources'' as above. Both are copies/clones and thus can be modified without affecting the variables that were passed in.

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T06:59:29Z

BAILOPAN: /* Protoc as a Tool */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]
* See [[#Protoc as a Tool]]

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

==Invoking protoc==
The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==C++ Protobuf Libraries==
To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

==Protoc as a Tool==

You can also embed generated protobufs directly into BinaryBuilders. For example:

<python>
prog = cxx.Program('prog')
protos = builder.tools.Protoc(sources = ['myproto.proto'])
prog.custom += [protos]
</python>

This compiles the pb.cc files in the same context as the binary. The <tt>Protoc()</tt> constructor takes two arguments:
<ul>
<li>''protoc'': Optional detected protoc. If omitted, <tt>DetectProtoc()</tt> is called automatically.</li>
<li>''sources'': Optional list of protobuf source files.</li>
</ul>

The return value is a <tt>ProtocJob</tt>, which has the attributes ''protoc'' and ''sources'' as above. Both are copies/clones and thus can be modified without affecting the variables that were passed in.

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T06:32:06Z

BAILOPAN: /* Protobufs */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]
* See [[#Protoc as a Tool]]

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

==Invoking protoc==
The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==C++ Protobuf Libraries==
To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

==Protoc as a Tool==

You can also embed generated protobufs directly into BinaryBuilders. For example:

<python>
prog = cxx.Program('prog')
protos = builder.tools.Protoc(sources = ['myproto.proto'])
prog.custom += [protos]
</python>

This compiles the pb.cc files in the same context as the binary. The <tt>Protoc()</tt> constructor takes two arguments:
<ul>
<li>''protoc'': Optional detected protoc. If omitted, <tt>DetectProtoc()</tt> is called automatically.</li>
<li>''sources'': Optional list of protobuf source files.</li>
</ul>

The return value is a <tt>ProtocJob</tt>, which has the attributes ''protoc'' and ''sources'' as given up. Both are clones and thus can be modified without affecting other callers.

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T06:26:34Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]
* See [[#Protoc as a Tool]]

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

==Invoking protoc==
The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==C++ Protobuf Libraries==
To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T06:26:06Z

BAILOPAN: /* Protobufs */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]
* See [[#Protoc as a Tool]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T06:25:08Z

BAILOPAN: /* Predefined Custom C++ Tools */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

==Invoking protoc==
The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==C++ Protobuf Libraries==
To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]
* See [[#Protoc as a Tool]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T06:02:16Z

BAILOPAN: /* Manual Invocation */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

==Invoking protoc==
The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==C++ Protobuf Libraries==
To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T06:02:02Z

BAILOPAN: /* C++ Libraries */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

==Manual Invocation==
The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==C++ Protobuf Libraries==
To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T06:01:50Z

BAILOPAN: /* Protobufs */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

==Manual Invocation==
The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==C++ Libraries==
To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T05:01:18Z

BAILOPAN: /* Protobufs */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

prog = builder.Program('myprogram')
prog.compiler.sourcedeps += out.headers
prog.compiler.linkflags += [out.lib.binary]
</python>

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-09T04:58:13Z

BAILOPAN: /* Protobufs */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

To make a static library out of generated protobufs, you can use the <tt>StaticLibrary</tt> helper, which takes the following arguments:
<ul>
<li>''name'': Binary name.</li>
<li>''builder'': Build context.</li>
<li>''cxx'': C++ compiler object from DetectCxx().</li>
<li>''sources'': List of protobuf files.</li>
<li>''includes'': Optional list of additional includes.</li>
</ul>

Example:

<python>
cxx = builder.DetectCxx()
protoc = builder.DetectProtoc()

proto_files = [
'game.proto',
'player.proto',
]
out = protoc.StaticLibrary('protos', builder, cxx, proto_files)

# Static library node is out.lib
# Header list (for adding to other BinaryBuilders via sourcedeps) is out.headers
</python>

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2023-11-08T06:35:17Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''DetectProtoc(**kwargs)'' - Detects the protobuf compiler (protoc). Only one kwarg is supported, path, which optionally specifies a specific binary to use for protoc. The returned <tt>Protoc</tt> object is documented under [[#Protobufs]]. This API is only available on 2.2.4 and higher.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

=Protobufs=

AMBuild has builtin support for protobufs as of version 2.2.4. The lowest-level way to use this support is via <tt>DetectProtoc()</tt>, which returns a <tt>Protoc</tt> object. This object has the following attributes:
<ul>
<li>''path'': Either 'protoc' or an explicitly given path to protoc.</li>
<li>''name'': The name reported by 'protoc --version', eg 'libprotoc'.</li>
<li>''version'': The protoc version, as a comparable object.</li>
<li>''extra_argv'': A list to add extra arguments to every protoc invocation.</li>
<li>''includes'': A list of include paths to add to every protoc invocation.</li>
</ul>

<tt>Protoc</tt> objects also have the following methods:
<ul>
<li>''clone'': Duplicate the <tt>Protoc</tt> object, except lists are copied to avoid affecting both <tt>Protoc</tt> objects.</li>
<li>''Generate'': Add build steps for compiling protobuf files.
</ul>

The <tt>Generate</tt> method takes the following arguments:
<ul>
<li>''builder'': A <tt>Context</tt> object.</li>
<li>''sources'': A list of source files.</li>
<li>''outputs'': A list of language targets. Each language target is either a language name, or a tuple of "(language name, folder)" where folder is None (build root) or an entry from <tt>builder.AddFolder()</tt>. Languages supported are 'cpp' and 'python'.</li>
<li>''includes'': A list of additional include paths.</li>
</ul>

<tt>Generate</tt> returns a dictionary to assist linking protoc outputs with other build rules. Each key of the dictionary is one of the languages requested:
<ul>
<li>'cpp': If cpp was requested, will contain a sub-dict with the keys 'sources' and 'headers'. Each of these is a list of <tt>Entry</tt> objects corresponding to the .pb.cc and .pb.h files created by protoc.</li>
<li>'python': If python was requested, will contain a sub-dict with the keys 'sources'. Each of these is a list of <tt>Entry</tt> objects corresponding to the _pb2.py files created by protoc.</li>
</ul>

Example of such a dict for 'game.proto' and 'player.proto' files, when all languages are requested:

<python>
{
'cpp': {
'sources': [Entry('game.pb.cc'), Entry('player.pb.cc')],
'headers': [Entry('game.pb.h'), Entry('player.pb.h')],
},
'python': {
'sources': [Entry('game_pb2.py'), Entry('player_pb2.py')],
},
}
</python>

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2021-11-22T05:33:57Z

BAILOPAN: /* Compiler */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

The <tt>Linker</tt> and <tt>Archiver</tt> objects both have a single method, <tt>link(name)</tt>, which returns whether the argument style derives from 'gcc' or 'msvc'.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2021-11-22T05:32:43Z

BAILOPAN: /* Attributes */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

The following attributes are available on 2.2.3 and higher:
* ''linker'' - A <tt>Linker</tt> object representing the linker (eg, ld or link.exe).
* ''linker_argv'' - Array of arguments to invoke the linker.
* ''archiver'' - An <tt>Archiver</tt> object representing the archiver (eg, ar or lib.exe).
* ''archiver_argv'' - Array of arguments to invoke the archiver.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild

2021-09-22T17:13:44Z

BAILOPAN:

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback on GitHub if you use it in your own projects.

AMBuild 2.2.1 is the latest release. It supports cross-compiling, multi-architecture builds, and precompiled headers.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 3.3 or higher is required.

Additionally, pip and setuptools (both Python components) are also required. If your distribution or Python installation does not provide for these, see [https://pip.pypa.io/en/stable/installing/ Installing Pip] for manual instructions.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: By default, pip will perform per-user installations. To install globally for all users, you will need to use "sudo" (or run as Administrator on Windows).

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. There is not an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

AMBuild API

2021-09-22T17:13:19Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.
* ''CallBuilder(fun)'' - Runs ''fun'' (a callback) in a child context. This is useful when a child folder is needed, but an entirely new build script would be too heavyweight. The return value of the function is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''linkdeps'' - An array of entries that will act as strong inputs to the linker. Normally, linker flags are scanned for paths to detect dependencies. This can fail if the linker flag is complicated or the path is embedded in a flag. In this case, the source path can be manually added to ''linkdeps''.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild

2020-08-25T04:05:18Z

BAILOPAN:

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback on GitHub if you use it in your own projects.

AMBuild 2.2 is the latest release. It supports cross-compiling, multi-architecture builds, and precompiled headers.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 2.7 or higher is required. If using Python 3, then 3.3 or higher is required.

Additionally, pip and setuptools (both Python components) are also required. If your distribution or Python installation does not provide for these, see [https://pip.pypa.io/en/stable/installing/ Installing Pip] for manual instructions.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: By default, pip will perform per-user installations. To install globally for all users, you will need to use "sudo" (or run as Administrator on Windows).

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. There is not an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

AMBuild

2020-08-25T04:04:49Z

BAILOPAN: /* Tup */

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback (see the bottom of this page) if you use it in your own projects.

AMBuild 2.2 is the latest release. It supports cross-compiling, multi-architecture builds, and precompiled headers.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 2.7 or higher is required. If using Python 3, then 3.3 or higher is required.

Additionally, pip and setuptools (both Python components) are also required. If your distribution or Python installation does not provide for these, see [https://pip.pypa.io/en/stable/installing/ Installing Pip] for manual instructions.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: By default, pip will perform per-user installations. To install globally for all users, you will need to use "sudo" (or run as Administrator on Windows).

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. There is not an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

AMBuild

2020-08-25T04:02:22Z

BAILOPAN: /* Make, Accuracy */

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback (see the bottom of this page) if you use it in your own projects.

AMBuild 2.2 is the latest release. It supports cross-compiling, multi-architecture builds, and precompiled headers.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 2.7 or higher is required. If using Python 3, then 3.3 or higher is required.

Additionally, pip and setuptools (both Python components) are also required. If your distribution or Python installation does not provide for these, see [https://pip.pypa.io/en/stable/installing/ Installing Pip] for manual instructions.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: By default, pip will perform per-user installations. To install globally for all users, you will need to use "sudo" (or run as Administrator on Windows).

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. There is not an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

==Tup==
AMBuild is designed to be, essentially, a miniature clone of Tup written entirely in Python. In particular it closely follows concepts in [http://gittup.org/tup/build_system_rules_and_algorithms.pdf the Tup whitepaper]. However there are a few differences that may make one more desirable over the other:
* Tup has been around longer than AMBuild 2, and has been more thoroughly tested.
* Tup uses complex file system features to optimize updates. Algorithms that are O(n) in AMBuild tend to be O(1) in Tup.
* AMBuild only requires a default Python installation to work. Tup, due to being written in C and using very platform specific file system features, may not be as accessible.
* Tup has more features for speeding up very large projects. It can do minimal reparsing and it can reduce the number of links in large graphs.
* AMBuild is designed to be a front-end in addition to a back-end. It has a simple API and script syntax, and is designed to support multiple output formats. For example, it could conceivably generate Visual Studio or XCode project files.

Since AMBuild is also a frontend, AMBuild may one day eliminate its backend in favor of emitting Tupfiles instead.

AMBuild's IPC implementation is very low-level, and it has not yet been ported beyond Windows, Mac/BSD, or Linux. However it's not difficult to port to Unix-like systems, and if needed a generic (albeit suboptimal) cross-platform implementation could be provided.

AMBuild Tutorial

2020-08-25T04:00:27Z

BAILOPAN: /* Multiple Scripts */

Writing project files with AMBuild is fairly easy. This tutorial will guide you through making simple AMBuild scripts to compile and package a C++ project.

For information on the full API, see [[AMBuild API]].

==Simple Project==
To begin, let's say we have a sample project with the following files:

<pre>
$ ls
goodbye.cpp helpers.cpp README.txt
</pre>

To start, we need to generate a default AMBuild configure script. This is the script that will perform the "configure" step for your build. You can generate one with the following command:

<pre>
$ ambuild --new-project
$ ls
AMBuildScript configure.py goodbye.cpp helpers.cpp README.txt
</pre>

The configure script simply invokes AMBuild. It can be modified (as we'll see later) to take extra command line options.
<pre>
$ cat configure.py
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys
from ambuild2 import run

prep = run.BuildParser(sys.path[0], api='2.2')
prep.Configure()
</pre>

Now, we're ready to actually make a build script for our project. The master build script must be a file called <tt>AMBuildScript</tt>, and it must be written in [http://python.org/ Python] syntax. The full Python API on your system is available to AMBuild scripts, but the important aspect we'll deal with here is the AMBuild API.

The first step is to tell AMBuild to detect the first available C or C++ compiler. This is done with the following line:
<Python>
cxx = builder.DetectCxx()
</Python>

With just this line in your build script, you can now try to configure build. You should see something like:
<pre>
$ mkdir build
$ cd build
$ python ../configure.py
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', 'test.cpp', '-o', 'testp']
found gcc version 4.7
$
</pre>

If you get an error - it's likely you don't have a compiler installed. Make sure gcc, clang, or Microsoft Visual Studio is available where appropriate.

Now, we're ready to complete our AMBuildScript:
<Python>
program = cxx.Program("hello")
program.sources = [
'main.cpp',
'helpers.cpp',
]
builder.Add(program)
</Python>

The <tt>builder</tt> object is an instance of an AMBuild ''context'' - more about this is in the [[AMBuild API]] documentation. Every AMBuild script has access to a <tt>builder</tt>. The <tt>builder.cxx</tt> object has information about the C/C++ compiler for the configure session. The <tt>Program()</tt> method will return an object used to create C++ compilation tasks. In this case, we're asking to build an executable that will be named 'hello' (or <tt>hello.exe</tt> on Windows). You can also specified shared libraries with <tt>Library</tt>, and static libraries with <tt>StaticLibrary</tt>.

You can attach a list of source files to your Program via the <tt>sources</tt> attribute. Finally, use <tt>builder.Add</tt> to take your C++ configuration and construct the necessary dependency graph and build steps.

Now, we can actually attempt to build. First, let's make sure AMBuild computed our graph and dependencies correctly:
<pre>
$ python ../configure.py
$ ambuild --show-graph
: mkdir "hello"
- hello/hello
- c++ main.o helpers.o -o hello
- hello/main.o
- [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
- /home/dvander/projects/ambuild/ambuild2/main.cpp
- hello/helpers.o
- [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
- /home/dvander/projects/ambuild/ambuild2/helpers.cpp
$ ambuild --show-steps
mkdir -p hello
task 0: [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
-> hello/main.o
task 1: [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
-> hello/helpers.o
task 2: c++ main.o helpers.o -o hello
-> hello/hello
</pre>

It looks good! Now we can build:
<pre>
$ ambuild
mkdir -p hello
Spawned task master (pid: 15563)
Spawned worker (pid: 15564)
Spawned worker (pid: 15565)
[15564] c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
[15565] c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
[15565] c++ main.o helpers.o -o hello
[15565] Child process terminating normally.
[15564] Child process terminating normally.
[15563] Child process terminating normally.
Build succeeded.
$ ./hello/hello
Hello!
</pre>

Note that AMBuild gives each C++ binary its own folder. For example, if you build a static library called <tt>egg.a</tt>, a shared library called <tt>egg.so</tt>, and an executable called <tt>egg</tt> all in the same folder, AMBuild will actually perform each of these builds in separate folders, and the binary paths will look like:
* <tt>egg.a/egg.a</tt>
* <tt>egg.so/egg.so</tt>
* <tt>egg/egg</tt>

This is to allow complex build scenarios where the same files are rebuilt multiple times.

==Packaging==

Now that our project builds, let's add to our build script so that we can create a build package. We'd like to make a folder we can zip or tar for distribution, with the following files:
* <tt>README.txt</tt>, our readme
* <tt>hello</tt>, our final binary

First, we have to add a step to the build to create the distribution folder:
<Python>
dist_folder = builder.AddFolder('dist')
</Python>

The return value from <tt>AddFolder</tt> is a dependency graph node, that we can use as an input to future steps.

Now we can copy our files:
<Python>
outputs = builder.Add(program)

folder = builder.AddFolder('dist')
builder.AddCopy(os.path.join(builder.sourcePath, 'README.txt'), folder)
builder.AddCopy(outputs.binary, folder)
</Python>

<tt>README.txt</tt> can be copied directly from the source tree. To copy the executable, we use the return value of <tt>builder.Add()</tt>. We could construct its path ourselves, but having the dependency object already available is much more convenient.

Now, when we build, we see:
<Python>
[5952] cp "/home/dvander/projects/ambuild/ambuild2/README.txt" "./dist/README.txt"
Spawned worker (pid: 5953)
[5952] c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
[5954] c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
[5954] c++ main.o helpers.o -o hello
[5954] cp "hello/hello" "./dist/hello"
</Python>

Since copying <tt>README.txt</tt> has no dependencies, it can execute in parallel with other jobs, even before compilation has finished. It won't be copied again unless <tt>README.txt</tt> changes. However the copy of <tt>hello/hello</tt> has to occur last. We can see that it succeeded with:
<pre>
$ ls -l dist/
total 12
-rwxr-xr-x 1 dvander dvander 7036 Oct 16 22:32 hello
-rw-r--r-- 1 dvander dvander 23 Oct 16 22:32 README.txt
</pre>

It is also possible to add a step to execute a command like "tar" or "zip", but there's a complication. There must be a dependency to every file that would be included in the command, otherwise, the commands might occur out of order. We are still looking into easier ways to automate this.

==Multiple Scripts==

Non-trivial projects usually need more than one build script. AMBuild allows build scripts to nest; any script can run another script. Each script gets its own <tt>builder</tt>, known internally as a ''context''. All jobs are created within a context and associated with that context. This allows AMBuild to reparse a minimal number of build scripts when a build script changes.

Contexts, by default, are associated with the folder they exist in relative to the source tree. For example, a build script in <tt>/source-tree/src/game/AMBuild</tt> will have a context associated with <tt>src/game</tt>. This folder structure is mirrored in the build folder, and all jobs occur within the context's local folder. For example, let's move our packaging into a separate script, <tt>PackageScript</tt>:

<Python>
# PackageScript
import os

builder.SetBuildFolder('dist')
builder.AddCopy(os.path.join(builder.sourcePath, 'README.txt'), '.')
builder.AddCopy(Hello.binary, '.')
</Python>

Then we modify our main <tt>AMBuildScript</tt>:
<Python>
# AMBuildScript
cxx = builder.DetectCxx()

program = cxx.Program("hello")
program.sources = [
'main.cpp',
'helpers.cpp',
]
outputs = builder.Add(program)

builder.Build(
['PackageScript'],
{ 'Hello': outputs }
)
</Python>

The first parameter is an array of script paths to run, and the second is a dictionary of global variables to give each script. Note that since our <tt>PackageScript</tt> is in the root of the source tree, by default its build folder is <tt>'.'</tt>, so we manually override its build folder.

When <tt>PackageScript</tt> is parsed during the configure step, all of its jobs will automatically be configured to occur inside a <tt>dist</tt> folder within the build folder, so <tt>'.'</tt> actually refers to <tt>./dist/</tt>.

If you have only one script, you can use <tt>Build</tt> instead. This also lets scripts return a value. For example:
<Python>
# AMBuildScript
folders = builder.Build('MakeFolders')
</Python>

<Python>
# MakeFolders
folders = [
builder.AddFolder('egg'),
builder.AddFolder('yam'),
builder.AddFolder('plant'),
]

# Magic variable; assigning to "rvalue" will propagate the value
# back up to Build().
rvalue = folders
</Python>

It is possible to pass variables to other scripts (they appear as global variables), or they can be attached to the <tt>builder</tt> object and they will automatically be propagated down. It's useful to propagate compiler objects this way, so they don't have to be re-detected and reconfigured in every subsequent script. For more information, see [[AMBuild API]].

For example, to pass our compiler around, we can use:
<Python>
# AMBuildScript
builder.cxx = builder.DetectCxx()
</Python>

Instead. This does not work for multi-architecture builds (for example, a single build producing x86 and x86_64 binaries), so if you support those, you will need a list of compilers instead.

==Custom Options==

It is possible to add custom options to the configure step using Python's [http://docs.python.org/2/library/optparse.html optparse] module. Recall the default <tt>configure.py</tt> that AMBuild generates:

<Python>
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys, ambuild2.run

parser = run.BuildParser(sys.path[0], api='2.2')
parser.Configure()
</Python>

The <tt>parser</tt> object has an <tt>options</tt> attribute, which is an instance of <tt>argparse.ArgumentParser</tt>. You can add to it, for example,

<Python>
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys, ambuild2.run

parser = run.BuildParser(sys.path[0], api='2.2')
parser.options.add_argument('--enable-debug', action='store_true', dest='debug', default=False,
help='Enable debugging symbols')
parser.options.add_argument('--enable-optimize', action='store_true', dest='opt', default=False,
help='Enable optimization')
parser.Configure()
</Python>

These options can be accessed from any <tt>builder</tt> object, like so:

<Python>
if builder.options.debug:
cxx.cflags += ['-O0', '-ggdb3']
cxx.cdefines += ['DEBUG']
if builder.options.opt:
cxx.cflags += ['-O3']
cxx.cdefines += ['NDEBUG']
</Python>

==Weak Dependencies==

Sometimes it is useful to force build steps to occur in distinct phases. Normally, this would be the antithesis of what we want: the dependency graph should precisely and perfectly represent dependencies, and there should be no need to enforce order manually. That's true, but there are situations that warrant relaxing how we construct the graph.

One example is generated headers in particular pose a problem. If we created dependencies on a "generate headers" task, then generating new headers would trigger recompiling every source file - even ones that never included those headers. Furthermore, if we created dependencies on each individual generated header, we'd have a huge dependency graph - 50 includes and 800 source files would mean 80,000 dependency links. AMBuild solves the first problem in the same way [http://gittup.org/tup/ tup] does. We do not yet attempt to solve the second problem, though it is planned for the future.

First, we introduce the concept of a ''weak dependency''. A weak dependency is one that theoretically exists, and must exist for ordering, but does not propagate damage. For example, let's say that <tt>hello.cpp</tt> has a weak dependency on <tt>generated.h</tt>. If <tt>hello.cpp</tt> doesn't <tt>#include "generated.h"</tt>, then no changes to <tt>generated.h</tt> should ever trigger a rebuild of <tt>hello.cpp</tt>. However, if <tt>hello.cpp</tt> is changed to include <tt>generated.h</tt>, then the weak dependency ensures those jobs are executed in the right order. (It is illegal in AMBuild to depend on a generated file without having an explicit dependency.) The weak dependency can then be upgraded to a strong dependency, and possibly downgraded again later if the <tt>#include</tt> is removed.

As an example, let's say we have two steps: generating headers and actual compilation. First, we add a shell command and save its outputs in a global variable.

<Python>
generated_headers = builder.AddCommand(
argv = ['python', os.path.join(builder.buildPath, 'tools', 'buildbot', 'generate_headers.py')],
inputs = [os.path.join(builder.sourcePath, '.hg', 'dirstate')],
outputs = ['sourcemod_auto_version.h']
)
</Python>

In another build script, assuming we communicated the <tt>headers</tt> object through, we could add:

<Python>
library = cxx.Library('cstrike')
library.sources = ['cstrike.cpp', 'smsdk_ext.cpp']
library.sourcedeps += generated_headers
builder.Add(library)
</Python>

And now when our generated headers change, we are guaranteed that if our library's sources need to be recompiled, they will be compiled after the headers are generated.

==Many Source Groups==

Projects may have complex components that form a single, monolithic unit. For example, portions of code may need certain compile options that other areas do not need. This can be accomplished in AMBuild using modules. For example, the root of a project might look like this:

<Python>
program = cxx.Program('sample')

builder.Build(['cairo/AMBuild', 'gtk/AMBuild'], {
'program': program
})

builder.Add(program)
</Python>

Then, <tt>cairo/AMBuild</tt> can do:
<Python>
module = program.Module(builder, 'cairo')
module.sources += [
'file.cc',
]
module.cxxflags += ['-Wno-flag-needed-for-cairo']
</Python>

The module will build as part of the entire binary.

==Reconfiguring==

Reconfiguring can happen for two reasons. One is if you change some properties of the build, for example, configuring a debug build over an existing optimized build. Another is if a build script changes, AMBuild will automatically reconfigure the build using the previous configure options.

===Output Cleaning===
When a reconfigure occurs, AMBuild will produce a new dependency graph alongside the old dependency graph, and these graphs are then merged. Any generated files in the old graph that are not present in the new graph are removed from the file system. This is necessary to ensure that builds do not become inconsistent or corrupt: every incremental build should be identical to a clean build.

For example, our object folder for our original script might look like:
<pre>
-rw-rw-r-- 1 dvander dvander 933 Nov 11 02:26 goodbye.o
-rw-rw-r-- 1 dvander dvander 1232 Nov 11 02:26 helpers.o
-rwxrwxr-x 1 dvander dvander 8509 Nov 11 02:26 sample
</pre>

If we comment out 'goodbye.cpp' from <tt>AMBuildScript</tt>, and build again:
<pre>
Reparsing build scripts.
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', '-fno-exceptions', '-fno-rtti', 'test.cpp', '-o', 'testp']
found gcc version 4.7
Removing old output: sample/goodbye.o
Spawned taskmaster (pid: 41899)
Spawned worker (pid: 41900)
[41900] c++ helpers.o -o sample
Build succeeded.
</pre>

And indeed, <tt>goodbye.o</tt> is gone:
<pre>
-rw-rw-r-- 1 dvander dvander 1232 Nov 11 02:26 helpers.o
-rwxrwxr-x 1 dvander dvander 8473 Nov 11 02:28 sample
</pre>

===Minimal Reparsing===
Unlike the normal dependency graph, AMBuild scripts can depend on each other. For example, a nested script may propagate a graph object back to the root script, which then propagates it down again. This creates an implicit cycle: if either script changes, the entire cycle must be reparsed. Avoiding this is extremely difficult as it is easy to construct situations in which a minimal reparse algorithm would fail. Thus, at the moment, AMBuild performs full reparses instead.

If this becomes a performance bottleneck, which it might in a huge project with hundreds of build scripts, we would like to implement minimal reparsing. It would likely require transitioning to a more restricted API that disallows (or discourages) arbitrary dataflow between build scripts. To solve the problem mentioned earlier, we would need specific functions that allow AMBuild to track script inter-dependencies.

Even with full reparsing however, AMBuild will only remove or rebuild individual jobs that have changed. If you add a single .cpp file to a source list, a full reparse will only result in that file being built and its binary relinked (and of course, any tasks depending on that binary).

===Refactoring===
Sometimes, it is useful to see whether changing build scripts would actually change the dependency graph. For example, refactoring them, or tracking down excessive rebuild problems. In Tup, this can be done with a "refactoring" build, and AMBuild (sort of) supports this feature. It is still new and may not catch all problems.

An example of a refactoring build where the dependency graph has changed:
<pre>
dvander@linux64:~/temp$ ambuild --refactor obj-linux-x86_64
Reparsing build scripts.
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', '-fno-exceptions', '-fno-rtti', 'test.cpp', '-o', 'testp']
found gcc version 4.7
New output introduced: sample
Failed to reparse build scripts.
</pre>

AMBuild Tutorial

2020-08-25T03:58:12Z

BAILOPAN: /* Multiple Scripts */

Writing project files with AMBuild is fairly easy. This tutorial will guide you through making simple AMBuild scripts to compile and package a C++ project.

For information on the full API, see [[AMBuild API]].

==Simple Project==
To begin, let's say we have a sample project with the following files:

<pre>
$ ls
goodbye.cpp helpers.cpp README.txt
</pre>

To start, we need to generate a default AMBuild configure script. This is the script that will perform the "configure" step for your build. You can generate one with the following command:

<pre>
$ ambuild --new-project
$ ls
AMBuildScript configure.py goodbye.cpp helpers.cpp README.txt
</pre>

The configure script simply invokes AMBuild. It can be modified (as we'll see later) to take extra command line options.
<pre>
$ cat configure.py
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys
from ambuild2 import run

prep = run.BuildParser(sys.path[0], api='2.2')
prep.Configure()
</pre>

Now, we're ready to actually make a build script for our project. The master build script must be a file called <tt>AMBuildScript</tt>, and it must be written in [http://python.org/ Python] syntax. The full Python API on your system is available to AMBuild scripts, but the important aspect we'll deal with here is the AMBuild API.

The first step is to tell AMBuild to detect the first available C or C++ compiler. This is done with the following line:
<Python>
cxx = builder.DetectCxx()
</Python>

With just this line in your build script, you can now try to configure build. You should see something like:
<pre>
$ mkdir build
$ cd build
$ python ../configure.py
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', 'test.cpp', '-o', 'testp']
found gcc version 4.7
$
</pre>

If you get an error - it's likely you don't have a compiler installed. Make sure gcc, clang, or Microsoft Visual Studio is available where appropriate.

Now, we're ready to complete our AMBuildScript:
<Python>
program = cxx.Program("hello")
program.sources = [
'main.cpp',
'helpers.cpp',
]
builder.Add(program)
</Python>

The <tt>builder</tt> object is an instance of an AMBuild ''context'' - more about this is in the [[AMBuild API]] documentation. Every AMBuild script has access to a <tt>builder</tt>. The <tt>builder.cxx</tt> object has information about the C/C++ compiler for the configure session. The <tt>Program()</tt> method will return an object used to create C++ compilation tasks. In this case, we're asking to build an executable that will be named 'hello' (or <tt>hello.exe</tt> on Windows). You can also specified shared libraries with <tt>Library</tt>, and static libraries with <tt>StaticLibrary</tt>.

You can attach a list of source files to your Program via the <tt>sources</tt> attribute. Finally, use <tt>builder.Add</tt> to take your C++ configuration and construct the necessary dependency graph and build steps.

Now, we can actually attempt to build. First, let's make sure AMBuild computed our graph and dependencies correctly:
<pre>
$ python ../configure.py
$ ambuild --show-graph
: mkdir "hello"
- hello/hello
- c++ main.o helpers.o -o hello
- hello/main.o
- [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
- /home/dvander/projects/ambuild/ambuild2/main.cpp
- hello/helpers.o
- [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
- /home/dvander/projects/ambuild/ambuild2/helpers.cpp
$ ambuild --show-steps
mkdir -p hello
task 0: [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
-> hello/main.o
task 1: [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
-> hello/helpers.o
task 2: c++ main.o helpers.o -o hello
-> hello/hello
</pre>

It looks good! Now we can build:
<pre>
$ ambuild
mkdir -p hello
Spawned task master (pid: 15563)
Spawned worker (pid: 15564)
Spawned worker (pid: 15565)
[15564] c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
[15565] c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
[15565] c++ main.o helpers.o -o hello
[15565] Child process terminating normally.
[15564] Child process terminating normally.
[15563] Child process terminating normally.
Build succeeded.
$ ./hello/hello
Hello!
</pre>

Note that AMBuild gives each C++ binary its own folder. For example, if you build a static library called <tt>egg.a</tt>, a shared library called <tt>egg.so</tt>, and an executable called <tt>egg</tt> all in the same folder, AMBuild will actually perform each of these builds in separate folders, and the binary paths will look like:
* <tt>egg.a/egg.a</tt>
* <tt>egg.so/egg.so</tt>
* <tt>egg/egg</tt>

This is to allow complex build scenarios where the same files are rebuilt multiple times.

==Packaging==

Now that our project builds, let's add to our build script so that we can create a build package. We'd like to make a folder we can zip or tar for distribution, with the following files:
* <tt>README.txt</tt>, our readme
* <tt>hello</tt>, our final binary

First, we have to add a step to the build to create the distribution folder:
<Python>
dist_folder = builder.AddFolder('dist')
</Python>

The return value from <tt>AddFolder</tt> is a dependency graph node, that we can use as an input to future steps.

Now we can copy our files:
<Python>
outputs = builder.Add(program)

folder = builder.AddFolder('dist')
builder.AddCopy(os.path.join(builder.sourcePath, 'README.txt'), folder)
builder.AddCopy(outputs.binary, folder)
</Python>

<tt>README.txt</tt> can be copied directly from the source tree. To copy the executable, we use the return value of <tt>builder.Add()</tt>. We could construct its path ourselves, but having the dependency object already available is much more convenient.

Now, when we build, we see:
<Python>
[5952] cp "/home/dvander/projects/ambuild/ambuild2/README.txt" "./dist/README.txt"
Spawned worker (pid: 5953)
[5952] c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
[5954] c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
[5954] c++ main.o helpers.o -o hello
[5954] cp "hello/hello" "./dist/hello"
</Python>

Since copying <tt>README.txt</tt> has no dependencies, it can execute in parallel with other jobs, even before compilation has finished. It won't be copied again unless <tt>README.txt</tt> changes. However the copy of <tt>hello/hello</tt> has to occur last. We can see that it succeeded with:
<pre>
$ ls -l dist/
total 12
-rwxr-xr-x 1 dvander dvander 7036 Oct 16 22:32 hello
-rw-r--r-- 1 dvander dvander 23 Oct 16 22:32 README.txt
</pre>

It is also possible to add a step to execute a command like "tar" or "zip", but there's a complication. There must be a dependency to every file that would be included in the command, otherwise, the commands might occur out of order. We are still looking into easier ways to automate this.

==Multiple Scripts==

Non-trivial projects usually need more than one build script. AMBuild allows build scripts to nest; any script can run another script. Each script gets its own <tt>builder</tt>, known internally as a ''context''. All jobs are created within a context and associated with that context. This allows AMBuild to reparse a minimal number of build scripts when a build script changes.

Contexts, by default, are associated with the folder they exist in relative to the source tree. For example, a build script in <tt>/source-tree/src/game/AMBuild</tt> will have a context associated with <tt>src/game</tt>. This folder structure is mirrored in the build folder, and all jobs occur within the context's local folder. For example, let's move our packaging into a separate script, <tt>PackageScript</tt>:

<Python>
# PackageScript
import os

builder.SetBuildFolder('dist')
builder.AddCopy(os.path.join(builder.sourcePath, 'README.txt'), '.')
builder.AddCopy(Hello.binary, '.')
</Python>

Then we modify our main <tt>AMBuildScript</tt>:
<Python>
# AMBuildScript
builder.DetectCxx()

program = cxx.Program("hello")
program.sources = [
'main.cpp',
'helpers.cpp',
]
outputs = builder.Add(program)

builder.Build(
['PackageScript'],
{ 'Hello': outputs }
)
</Python>

The first parameter is an array of script paths to run, and the second is a dictionary of global variables to give each script. Note that since our <tt>PackageScript</tt> is in the root of the source tree, by default its build folder is <tt>'.'</tt>, so we manually override its build folder.

When <tt>PackageScript</tt> is parsed during the configure step, all of its jobs will automatically be configured to occur inside a <tt>dist</tt> folder within the build folder, so <tt>'.'</tt> actually refers to <tt>./dist/</tt>.

If you have only one script, you can use <tt>Build</tt> instead. This also lets scripts return a value. For example:
<Python>
# AMBuildScript
folders = builder.Build('MakeFolders')
</Python>

<Python>
# MakeFolders
folders = [
builder.AddFolder('egg'),
builder.AddFolder('yam'),
builder.AddFolder('plant'),
]

# Magic variable; assigning to "rvalue" will propagate the value
# back up to Build().
rvalue = folders
</Python>

It is possible to pass variables to other scripts (they appear as global variables), or they can be attached to the <tt>builder</tt> object and they will automatically be propagated down. It's useful to propagate compiler objects this way, so they don't have to be re-detected and reconfigured in every subsequent script. For more information, see [[AMBuild API]].

==Custom Options==

It is possible to add custom options to the configure step using Python's [http://docs.python.org/2/library/optparse.html optparse] module. Recall the default <tt>configure.py</tt> that AMBuild generates:

<Python>
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys, ambuild2.run

parser = run.BuildParser(sys.path[0], api='2.2')
parser.Configure()
</Python>

The <tt>parser</tt> object has an <tt>options</tt> attribute, which is an instance of <tt>argparse.ArgumentParser</tt>. You can add to it, for example,

<Python>
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys, ambuild2.run

parser = run.BuildParser(sys.path[0], api='2.2')
parser.options.add_argument('--enable-debug', action='store_true', dest='debug', default=False,
help='Enable debugging symbols')
parser.options.add_argument('--enable-optimize', action='store_true', dest='opt', default=False,
help='Enable optimization')
parser.Configure()
</Python>

These options can be accessed from any <tt>builder</tt> object, like so:

<Python>
if builder.options.debug:
cxx.cflags += ['-O0', '-ggdb3']
cxx.cdefines += ['DEBUG']
if builder.options.opt:
cxx.cflags += ['-O3']
cxx.cdefines += ['NDEBUG']
</Python>

==Weak Dependencies==

Sometimes it is useful to force build steps to occur in distinct phases. Normally, this would be the antithesis of what we want: the dependency graph should precisely and perfectly represent dependencies, and there should be no need to enforce order manually. That's true, but there are situations that warrant relaxing how we construct the graph.

One example is generated headers in particular pose a problem. If we created dependencies on a "generate headers" task, then generating new headers would trigger recompiling every source file - even ones that never included those headers. Furthermore, if we created dependencies on each individual generated header, we'd have a huge dependency graph - 50 includes and 800 source files would mean 80,000 dependency links. AMBuild solves the first problem in the same way [http://gittup.org/tup/ tup] does. We do not yet attempt to solve the second problem, though it is planned for the future.

First, we introduce the concept of a ''weak dependency''. A weak dependency is one that theoretically exists, and must exist for ordering, but does not propagate damage. For example, let's say that <tt>hello.cpp</tt> has a weak dependency on <tt>generated.h</tt>. If <tt>hello.cpp</tt> doesn't <tt>#include "generated.h"</tt>, then no changes to <tt>generated.h</tt> should ever trigger a rebuild of <tt>hello.cpp</tt>. However, if <tt>hello.cpp</tt> is changed to include <tt>generated.h</tt>, then the weak dependency ensures those jobs are executed in the right order. (It is illegal in AMBuild to depend on a generated file without having an explicit dependency.) The weak dependency can then be upgraded to a strong dependency, and possibly downgraded again later if the <tt>#include</tt> is removed.

As an example, let's say we have two steps: generating headers and actual compilation. First, we add a shell command and save its outputs in a global variable.

<Python>
generated_headers = builder.AddCommand(
argv = ['python', os.path.join(builder.buildPath, 'tools', 'buildbot', 'generate_headers.py')],
inputs = [os.path.join(builder.sourcePath, '.hg', 'dirstate')],
outputs = ['sourcemod_auto_version.h']
)
</Python>

In another build script, assuming we communicated the <tt>headers</tt> object through, we could add:

<Python>
library = cxx.Library('cstrike')
library.sources = ['cstrike.cpp', 'smsdk_ext.cpp']
library.sourcedeps += generated_headers
builder.Add(library)
</Python>

And now when our generated headers change, we are guaranteed that if our library's sources need to be recompiled, they will be compiled after the headers are generated.

==Many Source Groups==

Projects may have complex components that form a single, monolithic unit. For example, portions of code may need certain compile options that other areas do not need. This can be accomplished in AMBuild using modules. For example, the root of a project might look like this:

<Python>
program = cxx.Program('sample')

builder.Build(['cairo/AMBuild', 'gtk/AMBuild'], {
'program': program
})

builder.Add(program)
</Python>

Then, <tt>cairo/AMBuild</tt> can do:
<Python>
module = program.Module(builder, 'cairo')
module.sources += [
'file.cc',
]
module.cxxflags += ['-Wno-flag-needed-for-cairo']
</Python>

The module will build as part of the entire binary.

==Reconfiguring==

Reconfiguring can happen for two reasons. One is if you change some properties of the build, for example, configuring a debug build over an existing optimized build. Another is if a build script changes, AMBuild will automatically reconfigure the build using the previous configure options.

===Output Cleaning===
When a reconfigure occurs, AMBuild will produce a new dependency graph alongside the old dependency graph, and these graphs are then merged. Any generated files in the old graph that are not present in the new graph are removed from the file system. This is necessary to ensure that builds do not become inconsistent or corrupt: every incremental build should be identical to a clean build.

For example, our object folder for our original script might look like:
<pre>
-rw-rw-r-- 1 dvander dvander 933 Nov 11 02:26 goodbye.o
-rw-rw-r-- 1 dvander dvander 1232 Nov 11 02:26 helpers.o
-rwxrwxr-x 1 dvander dvander 8509 Nov 11 02:26 sample
</pre>

If we comment out 'goodbye.cpp' from <tt>AMBuildScript</tt>, and build again:
<pre>
Reparsing build scripts.
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', '-fno-exceptions', '-fno-rtti', 'test.cpp', '-o', 'testp']
found gcc version 4.7
Removing old output: sample/goodbye.o
Spawned taskmaster (pid: 41899)
Spawned worker (pid: 41900)
[41900] c++ helpers.o -o sample
Build succeeded.
</pre>

And indeed, <tt>goodbye.o</tt> is gone:
<pre>
-rw-rw-r-- 1 dvander dvander 1232 Nov 11 02:26 helpers.o
-rwxrwxr-x 1 dvander dvander 8473 Nov 11 02:28 sample
</pre>

===Minimal Reparsing===
Unlike the normal dependency graph, AMBuild scripts can depend on each other. For example, a nested script may propagate a graph object back to the root script, which then propagates it down again. This creates an implicit cycle: if either script changes, the entire cycle must be reparsed. Avoiding this is extremely difficult as it is easy to construct situations in which a minimal reparse algorithm would fail. Thus, at the moment, AMBuild performs full reparses instead.

If this becomes a performance bottleneck, which it might in a huge project with hundreds of build scripts, we would like to implement minimal reparsing. It would likely require transitioning to a more restricted API that disallows (or discourages) arbitrary dataflow between build scripts. To solve the problem mentioned earlier, we would need specific functions that allow AMBuild to track script inter-dependencies.

Even with full reparsing however, AMBuild will only remove or rebuild individual jobs that have changed. If you add a single .cpp file to a source list, a full reparse will only result in that file being built and its binary relinked (and of course, any tasks depending on that binary).

===Refactoring===
Sometimes, it is useful to see whether changing build scripts would actually change the dependency graph. For example, refactoring them, or tracking down excessive rebuild problems. In Tup, this can be done with a "refactoring" build, and AMBuild (sort of) supports this feature. It is still new and may not catch all problems.

An example of a refactoring build where the dependency graph has changed:
<pre>
dvander@linux64:~/temp$ ambuild --refactor obj-linux-x86_64
Reparsing build scripts.
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', '-fno-exceptions', '-fno-rtti', 'test.cpp', '-o', 'testp']
found gcc version 4.7
New output introduced: sample
Failed to reparse build scripts.
</pre>

AMBuild Tutorial

2020-08-25T03:56:31Z

BAILOPAN: /* Multiple Scripts */

Writing project files with AMBuild is fairly easy. This tutorial will guide you through making simple AMBuild scripts to compile and package a C++ project.

For information on the full API, see [[AMBuild API]].

==Simple Project==
To begin, let's say we have a sample project with the following files:

<pre>
$ ls
goodbye.cpp helpers.cpp README.txt
</pre>

To start, we need to generate a default AMBuild configure script. This is the script that will perform the "configure" step for your build. You can generate one with the following command:

<pre>
$ ambuild --new-project
$ ls
AMBuildScript configure.py goodbye.cpp helpers.cpp README.txt
</pre>

The configure script simply invokes AMBuild. It can be modified (as we'll see later) to take extra command line options.
<pre>
$ cat configure.py
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys
from ambuild2 import run

prep = run.BuildParser(sys.path[0], api='2.2')
prep.Configure()
</pre>

Now, we're ready to actually make a build script for our project. The master build script must be a file called <tt>AMBuildScript</tt>, and it must be written in [http://python.org/ Python] syntax. The full Python API on your system is available to AMBuild scripts, but the important aspect we'll deal with here is the AMBuild API.

The first step is to tell AMBuild to detect the first available C or C++ compiler. This is done with the following line:
<Python>
cxx = builder.DetectCxx()
</Python>

With just this line in your build script, you can now try to configure build. You should see something like:
<pre>
$ mkdir build
$ cd build
$ python ../configure.py
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', 'test.cpp', '-o', 'testp']
found gcc version 4.7
$
</pre>

If you get an error - it's likely you don't have a compiler installed. Make sure gcc, clang, or Microsoft Visual Studio is available where appropriate.

Now, we're ready to complete our AMBuildScript:
<Python>
program = cxx.Program("hello")
program.sources = [
'main.cpp',
'helpers.cpp',
]
builder.Add(program)
</Python>

The <tt>builder</tt> object is an instance of an AMBuild ''context'' - more about this is in the [[AMBuild API]] documentation. Every AMBuild script has access to a <tt>builder</tt>. The <tt>builder.cxx</tt> object has information about the C/C++ compiler for the configure session. The <tt>Program()</tt> method will return an object used to create C++ compilation tasks. In this case, we're asking to build an executable that will be named 'hello' (or <tt>hello.exe</tt> on Windows). You can also specified shared libraries with <tt>Library</tt>, and static libraries with <tt>StaticLibrary</tt>.

You can attach a list of source files to your Program via the <tt>sources</tt> attribute. Finally, use <tt>builder.Add</tt> to take your C++ configuration and construct the necessary dependency graph and build steps.

Now, we can actually attempt to build. First, let's make sure AMBuild computed our graph and dependencies correctly:
<pre>
$ python ../configure.py
$ ambuild --show-graph
: mkdir "hello"
- hello/hello
- c++ main.o helpers.o -o hello
- hello/main.o
- [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
- /home/dvander/projects/ambuild/ambuild2/main.cpp
- hello/helpers.o
- [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
- /home/dvander/projects/ambuild/ambuild2/helpers.cpp
$ ambuild --show-steps
mkdir -p hello
task 0: [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
-> hello/main.o
task 1: [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
-> hello/helpers.o
task 2: c++ main.o helpers.o -o hello
-> hello/hello
</pre>

It looks good! Now we can build:
<pre>
$ ambuild
mkdir -p hello
Spawned task master (pid: 15563)
Spawned worker (pid: 15564)
Spawned worker (pid: 15565)
[15564] c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
[15565] c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
[15565] c++ main.o helpers.o -o hello
[15565] Child process terminating normally.
[15564] Child process terminating normally.
[15563] Child process terminating normally.
Build succeeded.
$ ./hello/hello
Hello!
</pre>

Note that AMBuild gives each C++ binary its own folder. For example, if you build a static library called <tt>egg.a</tt>, a shared library called <tt>egg.so</tt>, and an executable called <tt>egg</tt> all in the same folder, AMBuild will actually perform each of these builds in separate folders, and the binary paths will look like:
* <tt>egg.a/egg.a</tt>
* <tt>egg.so/egg.so</tt>
* <tt>egg/egg</tt>

This is to allow complex build scenarios where the same files are rebuilt multiple times.

==Packaging==

Now that our project builds, let's add to our build script so that we can create a build package. We'd like to make a folder we can zip or tar for distribution, with the following files:
* <tt>README.txt</tt>, our readme
* <tt>hello</tt>, our final binary

First, we have to add a step to the build to create the distribution folder:
<Python>
dist_folder = builder.AddFolder('dist')
</Python>

The return value from <tt>AddFolder</tt> is a dependency graph node, that we can use as an input to future steps.

Now we can copy our files:
<Python>
outputs = builder.Add(program)

folder = builder.AddFolder('dist')
builder.AddCopy(os.path.join(builder.sourcePath, 'README.txt'), folder)
builder.AddCopy(outputs.binary, folder)
</Python>

<tt>README.txt</tt> can be copied directly from the source tree. To copy the executable, we use the return value of <tt>builder.Add()</tt>. We could construct its path ourselves, but having the dependency object already available is much more convenient.

Now, when we build, we see:
<Python>
[5952] cp "/home/dvander/projects/ambuild/ambuild2/README.txt" "./dist/README.txt"
Spawned worker (pid: 5953)
[5952] c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
[5954] c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
[5954] c++ main.o helpers.o -o hello
[5954] cp "hello/hello" "./dist/hello"
</Python>

Since copying <tt>README.txt</tt> has no dependencies, it can execute in parallel with other jobs, even before compilation has finished. It won't be copied again unless <tt>README.txt</tt> changes. However the copy of <tt>hello/hello</tt> has to occur last. We can see that it succeeded with:
<pre>
$ ls -l dist/
total 12
-rwxr-xr-x 1 dvander dvander 7036 Oct 16 22:32 hello
-rw-r--r-- 1 dvander dvander 23 Oct 16 22:32 README.txt
</pre>

It is also possible to add a step to execute a command like "tar" or "zip", but there's a complication. There must be a dependency to every file that would be included in the command, otherwise, the commands might occur out of order. We are still looking into easier ways to automate this.

==Multiple Scripts==

Non-trivial projects usually need more than one build script. AMBuild allows build scripts to nest; any script can run another script. Each script gets its own <tt>builder</tt>, known internally as a ''context''. All jobs are created within a context and associated with that context. This allows AMBuild to reparse a minimal number of build scripts when a build script changes.

Contexts, by default, are associated with the folder they exist in relative to the source tree. For example, a build script in <tt>/source-tree/src/game/AMBuild</tt> will have a context associated with <tt>src/game</tt>. This folder structure is mirrored in the build folder, and all jobs occur within the context's local folder. For example, let's move our packaging into a separate script, <tt>PackageScript</tt>:

<Python>
# PackageScript
import os

builder.SetBuildFolder('dist')
builder.AddCopy(os.path.join(builder.sourcePath, 'README.txt'), '.')
builder.AddCopy(Hello.binary, '.')
</Python>

Then we modify our main <tt>AMBuildScript</tt>:
<Python>
# AMBuildScript
builder.DetectCxx()

program = cxx.Program("hello")
program.sources = [
'main.cpp',
'helpers.cpp',
]
outputs = builder.Add(program)

builder.Build(
['PackageScript'],
{ 'Hello': outputs }
)
</Python>

The first parameter is an array of script paths to run, and the second is a dictionary of global variables to give each script. Note that since our <tt>PackageScript</tt> is in the root of the source tree, by default its build folder is <tt>'.'</tt>, so we manually override its build folder.

When <tt>PackageScript</tt> is parsed during the configure step, all of its jobs will automatically be configured to occur inside a <tt>dist</tt> folder within the build folder, so <tt>'.'</tt> actually refers to <tt>./dist/</tt>.

If you have only one script, you can use <tt>Build</tt> instead. This also lets scripts return a value. For example:
<Python>
# AMBuildScript
folders = builder.Build('MakeFolders')
</Python>

<Python>
# MakeFolders
folders = [
builder.AddFolder('egg'),
builder.AddFolder('yam'),
builder.AddFolder('plant'),
]

# Magic variable; assigning to "rvalue" will propagate the value
# back up to Build().
rvalue = folders
</Python>

It is possible to pass variables to other scripts (they appear as global variables), or they can be attached to the <tt>builder</tt> object and they will automatically be propagated down. It's useful to propagate compiler objects this way, so they don't have to be re-detected and reconfigured in every subsequent script.

==Custom Options==

It is possible to add custom options to the configure step using Python's [http://docs.python.org/2/library/optparse.html optparse] module. Recall the default <tt>configure.py</tt> that AMBuild generates:

<Python>
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys, ambuild2.run

parser = run.BuildParser(sys.path[0], api='2.2')
parser.Configure()
</Python>

The <tt>parser</tt> object has an <tt>options</tt> attribute, which is an instance of <tt>argparse.ArgumentParser</tt>. You can add to it, for example,

<Python>
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys, ambuild2.run

parser = run.BuildParser(sys.path[0], api='2.2')
parser.options.add_argument('--enable-debug', action='store_true', dest='debug', default=False,
help='Enable debugging symbols')
parser.options.add_argument('--enable-optimize', action='store_true', dest='opt', default=False,
help='Enable optimization')
parser.Configure()
</Python>

These options can be accessed from any <tt>builder</tt> object, like so:

<Python>
if builder.options.debug:
cxx.cflags += ['-O0', '-ggdb3']
cxx.cdefines += ['DEBUG']
if builder.options.opt:
cxx.cflags += ['-O3']
cxx.cdefines += ['NDEBUG']
</Python>

==Weak Dependencies==

Sometimes it is useful to force build steps to occur in distinct phases. Normally, this would be the antithesis of what we want: the dependency graph should precisely and perfectly represent dependencies, and there should be no need to enforce order manually. That's true, but there are situations that warrant relaxing how we construct the graph.

One example is generated headers in particular pose a problem. If we created dependencies on a "generate headers" task, then generating new headers would trigger recompiling every source file - even ones that never included those headers. Furthermore, if we created dependencies on each individual generated header, we'd have a huge dependency graph - 50 includes and 800 source files would mean 80,000 dependency links. AMBuild solves the first problem in the same way [http://gittup.org/tup/ tup] does. We do not yet attempt to solve the second problem, though it is planned for the future.

First, we introduce the concept of a ''weak dependency''. A weak dependency is one that theoretically exists, and must exist for ordering, but does not propagate damage. For example, let's say that <tt>hello.cpp</tt> has a weak dependency on <tt>generated.h</tt>. If <tt>hello.cpp</tt> doesn't <tt>#include "generated.h"</tt>, then no changes to <tt>generated.h</tt> should ever trigger a rebuild of <tt>hello.cpp</tt>. However, if <tt>hello.cpp</tt> is changed to include <tt>generated.h</tt>, then the weak dependency ensures those jobs are executed in the right order. (It is illegal in AMBuild to depend on a generated file without having an explicit dependency.) The weak dependency can then be upgraded to a strong dependency, and possibly downgraded again later if the <tt>#include</tt> is removed.

As an example, let's say we have two steps: generating headers and actual compilation. First, we add a shell command and save its outputs in a global variable.

<Python>
generated_headers = builder.AddCommand(
argv = ['python', os.path.join(builder.buildPath, 'tools', 'buildbot', 'generate_headers.py')],
inputs = [os.path.join(builder.sourcePath, '.hg', 'dirstate')],
outputs = ['sourcemod_auto_version.h']
)
</Python>

In another build script, assuming we communicated the <tt>headers</tt> object through, we could add:

<Python>
library = cxx.Library('cstrike')
library.sources = ['cstrike.cpp', 'smsdk_ext.cpp']
library.sourcedeps += generated_headers
builder.Add(library)
</Python>

And now when our generated headers change, we are guaranteed that if our library's sources need to be recompiled, they will be compiled after the headers are generated.

==Many Source Groups==

Projects may have complex components that form a single, monolithic unit. For example, portions of code may need certain compile options that other areas do not need. This can be accomplished in AMBuild using modules. For example, the root of a project might look like this:

<Python>
program = cxx.Program('sample')

builder.Build(['cairo/AMBuild', 'gtk/AMBuild'], {
'program': program
})

builder.Add(program)
</Python>

Then, <tt>cairo/AMBuild</tt> can do:
<Python>
module = program.Module(builder, 'cairo')
module.sources += [
'file.cc',
]
module.cxxflags += ['-Wno-flag-needed-for-cairo']
</Python>

The module will build as part of the entire binary.

==Reconfiguring==

Reconfiguring can happen for two reasons. One is if you change some properties of the build, for example, configuring a debug build over an existing optimized build. Another is if a build script changes, AMBuild will automatically reconfigure the build using the previous configure options.

===Output Cleaning===
When a reconfigure occurs, AMBuild will produce a new dependency graph alongside the old dependency graph, and these graphs are then merged. Any generated files in the old graph that are not present in the new graph are removed from the file system. This is necessary to ensure that builds do not become inconsistent or corrupt: every incremental build should be identical to a clean build.

For example, our object folder for our original script might look like:
<pre>
-rw-rw-r-- 1 dvander dvander 933 Nov 11 02:26 goodbye.o
-rw-rw-r-- 1 dvander dvander 1232 Nov 11 02:26 helpers.o
-rwxrwxr-x 1 dvander dvander 8509 Nov 11 02:26 sample
</pre>

If we comment out 'goodbye.cpp' from <tt>AMBuildScript</tt>, and build again:
<pre>
Reparsing build scripts.
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', '-fno-exceptions', '-fno-rtti', 'test.cpp', '-o', 'testp']
found gcc version 4.7
Removing old output: sample/goodbye.o
Spawned taskmaster (pid: 41899)
Spawned worker (pid: 41900)
[41900] c++ helpers.o -o sample
Build succeeded.
</pre>

And indeed, <tt>goodbye.o</tt> is gone:
<pre>
-rw-rw-r-- 1 dvander dvander 1232 Nov 11 02:26 helpers.o
-rwxrwxr-x 1 dvander dvander 8473 Nov 11 02:28 sample
</pre>

===Minimal Reparsing===
Unlike the normal dependency graph, AMBuild scripts can depend on each other. For example, a nested script may propagate a graph object back to the root script, which then propagates it down again. This creates an implicit cycle: if either script changes, the entire cycle must be reparsed. Avoiding this is extremely difficult as it is easy to construct situations in which a minimal reparse algorithm would fail. Thus, at the moment, AMBuild performs full reparses instead.

If this becomes a performance bottleneck, which it might in a huge project with hundreds of build scripts, we would like to implement minimal reparsing. It would likely require transitioning to a more restricted API that disallows (or discourages) arbitrary dataflow between build scripts. To solve the problem mentioned earlier, we would need specific functions that allow AMBuild to track script inter-dependencies.

Even with full reparsing however, AMBuild will only remove or rebuild individual jobs that have changed. If you add a single .cpp file to a source list, a full reparse will only result in that file being built and its binary relinked (and of course, any tasks depending on that binary).

===Refactoring===
Sometimes, it is useful to see whether changing build scripts would actually change the dependency graph. For example, refactoring them, or tracking down excessive rebuild problems. In Tup, this can be done with a "refactoring" build, and AMBuild (sort of) supports this feature. It is still new and may not catch all problems.

An example of a refactoring build where the dependency graph has changed:
<pre>
dvander@linux64:~/temp$ ambuild --refactor obj-linux-x86_64
Reparsing build scripts.
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', '-fno-exceptions', '-fno-rtti', 'test.cpp', '-o', 'testp']
found gcc version 4.7
New output introduced: sample
Failed to reparse build scripts.
</pre>

AMBuild Tutorial

2020-08-25T03:55:03Z

BAILOPAN:

Writing project files with AMBuild is fairly easy. This tutorial will guide you through making simple AMBuild scripts to compile and package a C++ project.

For information on the full API, see [[AMBuild API]].

==Simple Project==
To begin, let's say we have a sample project with the following files:

<pre>
$ ls
goodbye.cpp helpers.cpp README.txt
</pre>

To start, we need to generate a default AMBuild configure script. This is the script that will perform the "configure" step for your build. You can generate one with the following command:

<pre>
$ ambuild --new-project
$ ls
AMBuildScript configure.py goodbye.cpp helpers.cpp README.txt
</pre>

The configure script simply invokes AMBuild. It can be modified (as we'll see later) to take extra command line options.
<pre>
$ cat configure.py
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys
from ambuild2 import run

prep = run.BuildParser(sys.path[0], api='2.2')
prep.Configure()
</pre>

Now, we're ready to actually make a build script for our project. The master build script must be a file called <tt>AMBuildScript</tt>, and it must be written in [http://python.org/ Python] syntax. The full Python API on your system is available to AMBuild scripts, but the important aspect we'll deal with here is the AMBuild API.

The first step is to tell AMBuild to detect the first available C or C++ compiler. This is done with the following line:
<Python>
cxx = builder.DetectCxx()
</Python>

With just this line in your build script, you can now try to configure build. You should see something like:
<pre>
$ mkdir build
$ cd build
$ python ../configure.py
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', 'test.cpp', '-o', 'testp']
found gcc version 4.7
$
</pre>

If you get an error - it's likely you don't have a compiler installed. Make sure gcc, clang, or Microsoft Visual Studio is available where appropriate.

Now, we're ready to complete our AMBuildScript:
<Python>
program = cxx.Program("hello")
program.sources = [
'main.cpp',
'helpers.cpp',
]
builder.Add(program)
</Python>

The <tt>builder</tt> object is an instance of an AMBuild ''context'' - more about this is in the [[AMBuild API]] documentation. Every AMBuild script has access to a <tt>builder</tt>. The <tt>builder.cxx</tt> object has information about the C/C++ compiler for the configure session. The <tt>Program()</tt> method will return an object used to create C++ compilation tasks. In this case, we're asking to build an executable that will be named 'hello' (or <tt>hello.exe</tt> on Windows). You can also specified shared libraries with <tt>Library</tt>, and static libraries with <tt>StaticLibrary</tt>.

You can attach a list of source files to your Program via the <tt>sources</tt> attribute. Finally, use <tt>builder.Add</tt> to take your C++ configuration and construct the necessary dependency graph and build steps.

Now, we can actually attempt to build. First, let's make sure AMBuild computed our graph and dependencies correctly:
<pre>
$ python ../configure.py
$ ambuild --show-graph
: mkdir "hello"
- hello/hello
- c++ main.o helpers.o -o hello
- hello/main.o
- [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
- /home/dvander/projects/ambuild/ambuild2/main.cpp
- hello/helpers.o
- [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
- /home/dvander/projects/ambuild/ambuild2/helpers.cpp
$ ambuild --show-steps
mkdir -p hello
task 0: [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
-> hello/main.o
task 1: [gcc] -> c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
-> hello/helpers.o
task 2: c++ main.o helpers.o -o hello
-> hello/hello
</pre>

It looks good! Now we can build:
<pre>
$ ambuild
mkdir -p hello
Spawned task master (pid: 15563)
Spawned worker (pid: 15564)
Spawned worker (pid: 15565)
[15564] c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
[15565] c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
[15565] c++ main.o helpers.o -o hello
[15565] Child process terminating normally.
[15564] Child process terminating normally.
[15563] Child process terminating normally.
Build succeeded.
$ ./hello/hello
Hello!
</pre>

Note that AMBuild gives each C++ binary its own folder. For example, if you build a static library called <tt>egg.a</tt>, a shared library called <tt>egg.so</tt>, and an executable called <tt>egg</tt> all in the same folder, AMBuild will actually perform each of these builds in separate folders, and the binary paths will look like:
* <tt>egg.a/egg.a</tt>
* <tt>egg.so/egg.so</tt>
* <tt>egg/egg</tt>

This is to allow complex build scenarios where the same files are rebuilt multiple times.

==Packaging==

Now that our project builds, let's add to our build script so that we can create a build package. We'd like to make a folder we can zip or tar for distribution, with the following files:
* <tt>README.txt</tt>, our readme
* <tt>hello</tt>, our final binary

First, we have to add a step to the build to create the distribution folder:
<Python>
dist_folder = builder.AddFolder('dist')
</Python>

The return value from <tt>AddFolder</tt> is a dependency graph node, that we can use as an input to future steps.

Now we can copy our files:
<Python>
outputs = builder.Add(program)

folder = builder.AddFolder('dist')
builder.AddCopy(os.path.join(builder.sourcePath, 'README.txt'), folder)
builder.AddCopy(outputs.binary, folder)
</Python>

<tt>README.txt</tt> can be copied directly from the source tree. To copy the executable, we use the return value of <tt>builder.Add()</tt>. We could construct its path ourselves, but having the dependency object already available is much more convenient.

Now, when we build, we see:
<Python>
[5952] cp "/home/dvander/projects/ambuild/ambuild2/README.txt" "./dist/README.txt"
Spawned worker (pid: 5953)
[5952] c++ -H -c /home/dvander/projects/ambuild/ambuild2/helpers.cpp -o helpers.o
[5954] c++ -H -c /home/dvander/projects/ambuild/ambuild2/main.cpp -o main.o
[5954] c++ main.o helpers.o -o hello
[5954] cp "hello/hello" "./dist/hello"
</Python>

Since copying <tt>README.txt</tt> has no dependencies, it can execute in parallel with other jobs, even before compilation has finished. It won't be copied again unless <tt>README.txt</tt> changes. However the copy of <tt>hello/hello</tt> has to occur last. We can see that it succeeded with:
<pre>
$ ls -l dist/
total 12
-rwxr-xr-x 1 dvander dvander 7036 Oct 16 22:32 hello
-rw-r--r-- 1 dvander dvander 23 Oct 16 22:32 README.txt
</pre>

It is also possible to add a step to execute a command like "tar" or "zip", but there's a complication. There must be a dependency to every file that would be included in the command, otherwise, the commands might occur out of order. We are still looking into easier ways to automate this.

==Multiple Scripts==

Non-trivial projects usually need more than one build script. AMBuild allows build scripts to nest; any script can run another script. Each script gets its own <tt>builder</tt>, known internally as a ''context''. All jobs are created within a context and associated with that context. This allows AMBuild to reparse a minimal number of build scripts when a build script changes.

Contexts, by default, are associated with the folder they exist in relative to the source tree. For example, a build script in <tt>/source-tree/src/game/AMBuild</tt> will have a context associated with <tt>src/game</tt>. This folder structure is mirrored in the build folder, and all jobs occur within the context's local folder. For example, let's move our packaging into a separate script, <tt>PackageScript</tt>:

<Python>
# PackageScript
import os

builder.SetBuildFolder('dist')
builder.AddCopy(os.path.join(builder.sourcePath, 'README.txt'), '.')
builder.AddCopy(Hello.binary, '.')
</Python>

Then we modify our main <tt>AMBuildScript</tt>:
<Python>
# AMBuildScript
builder.DetectCxx()

program = cxx.Program("hello")
program.sources = [
'main.cpp',
'helpers.cpp',
]
outputs = builder.Add(program)

builder.Build(
['PackageScript'],
{ 'Hello': outputs }
)
</Python>

The first parameter is an array of script paths to run, and the second is a dictionary of global variables to give each script. Note that since our <tt>PackageScript</tt> is in the root of the source tree, by default its build folder is <tt>'.'</tt>, so we manually override its build folder.

When <tt>PackageScript</tt> is parsed during the configure step, all of its jobs will automatically be configured to occur inside a <tt>dist</tt> folder within the build folder, so <tt>'.'</tt> actually refers to <tt>./dist/</tt>.

If you have only one script, you can use <tt>Build</tt> instead. This also lets scripts return a value. For example:
<Python>
# AMBuildScript
folders = builder.Build('MakeFolders')
</Python>

<Python>
# MakeFolders
folders = [
builder.AddFolder('egg'),
builder.AddFolder('yam'),
builder.AddFolder('plant'),
]

# Magic variable; assigning to "rvalue" will propagate the value
# back up to Build().
rvalue = folders
</Python>

==Custom Options==

It is possible to add custom options to the configure step using Python's [http://docs.python.org/2/library/optparse.html optparse] module. Recall the default <tt>configure.py</tt> that AMBuild generates:

<Python>
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys, ambuild2.run

parser = run.BuildParser(sys.path[0], api='2.2')
parser.Configure()
</Python>

The <tt>parser</tt> object has an <tt>options</tt> attribute, which is an instance of <tt>argparse.ArgumentParser</tt>. You can add to it, for example,

<Python>
# vim: set sts=2 ts=8 sw=2 tw=99 noet:
import sys, ambuild2.run

parser = run.BuildParser(sys.path[0], api='2.2')
parser.options.add_argument('--enable-debug', action='store_true', dest='debug', default=False,
help='Enable debugging symbols')
parser.options.add_argument('--enable-optimize', action='store_true', dest='opt', default=False,
help='Enable optimization')
parser.Configure()
</Python>

These options can be accessed from any <tt>builder</tt> object, like so:

<Python>
if builder.options.debug:
cxx.cflags += ['-O0', '-ggdb3']
cxx.cdefines += ['DEBUG']
if builder.options.opt:
cxx.cflags += ['-O3']
cxx.cdefines += ['NDEBUG']
</Python>

==Weak Dependencies==

Sometimes it is useful to force build steps to occur in distinct phases. Normally, this would be the antithesis of what we want: the dependency graph should precisely and perfectly represent dependencies, and there should be no need to enforce order manually. That's true, but there are situations that warrant relaxing how we construct the graph.

One example is generated headers in particular pose a problem. If we created dependencies on a "generate headers" task, then generating new headers would trigger recompiling every source file - even ones that never included those headers. Furthermore, if we created dependencies on each individual generated header, we'd have a huge dependency graph - 50 includes and 800 source files would mean 80,000 dependency links. AMBuild solves the first problem in the same way [http://gittup.org/tup/ tup] does. We do not yet attempt to solve the second problem, though it is planned for the future.

First, we introduce the concept of a ''weak dependency''. A weak dependency is one that theoretically exists, and must exist for ordering, but does not propagate damage. For example, let's say that <tt>hello.cpp</tt> has a weak dependency on <tt>generated.h</tt>. If <tt>hello.cpp</tt> doesn't <tt>#include "generated.h"</tt>, then no changes to <tt>generated.h</tt> should ever trigger a rebuild of <tt>hello.cpp</tt>. However, if <tt>hello.cpp</tt> is changed to include <tt>generated.h</tt>, then the weak dependency ensures those jobs are executed in the right order. (It is illegal in AMBuild to depend on a generated file without having an explicit dependency.) The weak dependency can then be upgraded to a strong dependency, and possibly downgraded again later if the <tt>#include</tt> is removed.

As an example, let's say we have two steps: generating headers and actual compilation. First, we add a shell command and save its outputs in a global variable.

<Python>
generated_headers = builder.AddCommand(
argv = ['python', os.path.join(builder.buildPath, 'tools', 'buildbot', 'generate_headers.py')],
inputs = [os.path.join(builder.sourcePath, '.hg', 'dirstate')],
outputs = ['sourcemod_auto_version.h']
)
</Python>

In another build script, assuming we communicated the <tt>headers</tt> object through, we could add:

<Python>
library = cxx.Library('cstrike')
library.sources = ['cstrike.cpp', 'smsdk_ext.cpp']
library.sourcedeps += generated_headers
builder.Add(library)
</Python>

And now when our generated headers change, we are guaranteed that if our library's sources need to be recompiled, they will be compiled after the headers are generated.

==Many Source Groups==

Projects may have complex components that form a single, monolithic unit. For example, portions of code may need certain compile options that other areas do not need. This can be accomplished in AMBuild using modules. For example, the root of a project might look like this:

<Python>
program = cxx.Program('sample')

builder.Build(['cairo/AMBuild', 'gtk/AMBuild'], {
'program': program
})

builder.Add(program)
</Python>

Then, <tt>cairo/AMBuild</tt> can do:
<Python>
module = program.Module(builder, 'cairo')
module.sources += [
'file.cc',
]
module.cxxflags += ['-Wno-flag-needed-for-cairo']
</Python>

The module will build as part of the entire binary.

==Reconfiguring==

Reconfiguring can happen for two reasons. One is if you change some properties of the build, for example, configuring a debug build over an existing optimized build. Another is if a build script changes, AMBuild will automatically reconfigure the build using the previous configure options.

===Output Cleaning===
When a reconfigure occurs, AMBuild will produce a new dependency graph alongside the old dependency graph, and these graphs are then merged. Any generated files in the old graph that are not present in the new graph are removed from the file system. This is necessary to ensure that builds do not become inconsistent or corrupt: every incremental build should be identical to a clean build.

For example, our object folder for our original script might look like:
<pre>
-rw-rw-r-- 1 dvander dvander 933 Nov 11 02:26 goodbye.o
-rw-rw-r-- 1 dvander dvander 1232 Nov 11 02:26 helpers.o
-rwxrwxr-x 1 dvander dvander 8509 Nov 11 02:26 sample
</pre>

If we comment out 'goodbye.cpp' from <tt>AMBuildScript</tt>, and build again:
<pre>
Reparsing build scripts.
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', '-fno-exceptions', '-fno-rtti', 'test.cpp', '-o', 'testp']
found gcc version 4.7
Removing old output: sample/goodbye.o
Spawned taskmaster (pid: 41899)
Spawned worker (pid: 41900)
[41900] c++ helpers.o -o sample
Build succeeded.
</pre>

And indeed, <tt>goodbye.o</tt> is gone:
<pre>
-rw-rw-r-- 1 dvander dvander 1232 Nov 11 02:26 helpers.o
-rwxrwxr-x 1 dvander dvander 8473 Nov 11 02:28 sample
</pre>

===Minimal Reparsing===
Unlike the normal dependency graph, AMBuild scripts can depend on each other. For example, a nested script may propagate a graph object back to the root script, which then propagates it down again. This creates an implicit cycle: if either script changes, the entire cycle must be reparsed. Avoiding this is extremely difficult as it is easy to construct situations in which a minimal reparse algorithm would fail. Thus, at the moment, AMBuild performs full reparses instead.

If this becomes a performance bottleneck, which it might in a huge project with hundreds of build scripts, we would like to implement minimal reparsing. It would likely require transitioning to a more restricted API that disallows (or discourages) arbitrary dataflow between build scripts. To solve the problem mentioned earlier, we would need specific functions that allow AMBuild to track script inter-dependencies.

Even with full reparsing however, AMBuild will only remove or rebuild individual jobs that have changed. If you add a single .cpp file to a source list, a full reparse will only result in that file being built and its binary relinked (and of course, any tasks depending on that binary).

===Refactoring===
Sometimes, it is useful to see whether changing build scripts would actually change the dependency graph. For example, refactoring them, or tracking down excessive rebuild problems. In Tup, this can be done with a "refactoring" build, and AMBuild (sort of) supports this feature. It is still new and may not catch all problems.

An example of a refactoring build where the dependency graph has changed:
<pre>
dvander@linux64:~/temp$ ambuild --refactor obj-linux-x86_64
Reparsing build scripts.
Checking CC compiler (vendor test gcc)... ['cc', 'test.c', '-o', 'test']
found gcc version 4.7
Checking CXX compiler (vendor test gcc)... ['c++', '-fno-exceptions', '-fno-rtti', 'test.cpp', '-o', 'testp']
found gcc version 4.7
New output introduced: sample
Failed to reparse build scripts.
</pre>

AMBuild

2020-08-25T03:50:58Z

BAILOPAN:

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback (see the bottom of this page) if you use it in your own projects.

AMBuild 2.2 is the latest release. It supports cross-compiling, multi-architecture builds, and precompiled headers.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 2.7 or higher is required. If using Python 3, then 3.3 or higher is required.

Additionally, pip and setuptools (both Python components) are also required. If your distribution or Python installation does not provide for these, see [https://pip.pypa.io/en/stable/installing/ Installing Pip] for manual instructions.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: By default, pip will perform per-user installations. To install globally for all users, you will need to use "sudo" (or run as Administrator on Windows).

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. The author is not aware of an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

==Tup==
AMBuild is designed to be, essentially, a miniature clone of Tup written entirely in Python. In particular it closely follows concepts in [http://gittup.org/tup/build_system_rules_and_algorithms.pdf the Tup whitepaper]. However there are a few differences that may make one more desirable over the other:
* Tup has been around longer than AMBuild 2, and has been more thoroughly tested.
* Tup uses complex file system features to optimize updates. Algorithms that are O(n) in AMBuild tend to be O(1) in Tup.
* AMBuild only requires a default Python installation to work. Tup, due to being written in C and using very platform specific file system features, may not be as accessible.
* Tup has more features for speeding up very large projects. It can do minimal reparsing and it can reduce the number of links in large graphs.
* AMBuild is designed to be a front-end in addition to a back-end. It has a simple API and script syntax, and is designed to support multiple output formats. For example, it could conceivably generate Visual Studio or XCode project files.

Since AMBuild is also a frontend, AMBuild may one day eliminate its backend in favor of emitting Tupfiles instead.

AMBuild's IPC implementation is very low-level, and it has not yet been ported beyond Windows, Mac/BSD, or Linux. However it's not difficult to port to Unix-like systems, and if needed a generic (albeit suboptimal) cross-platform implementation could be provided.

AMBuild API

2020-08-25T03:32:52Z

BAILOPAN: /* Changes from 2.1 */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. The main use case was for tricking the linker into linking to a local symlink. This can be achieved by adding the file name as a linker flag, and including an <tt>AddSymlink</tt> node in <tt>weaklinkdeps</tt>.
* AddCommand no longer returns a (node, (entry...)) tuple. Instead, it returns a list of entries.
* AddCopy and AddSymlink no longer return a (node, (entry...)) tuple. Instead, they both return a single entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-25T03:14:30Z

BAILOPAN: /* Changes from 2.1 */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. In the obscure cases where it was needed, <tt>weaklinkdeps</tt> and <tt>entry</tt> objects can be used instead.
* AddCommand, AddCopy, and AddSymlink no longer return command nodes. They return only entries, and the copy/symlink variants return only one entry.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-25T03:13:48Z

BAILOPAN: /* Methods */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy. Returns the <tt>Entry</tt> for the new file.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** Returns the <tt>Entry</tt> for the new file.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. In the obscure cases where it was needed, <tt>weaklinkdeps</tt> and <tt>entry</tt> objects can be used instead.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-25T03:07:31Z

BAILOPAN: /* Changes from 2.1 */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. In the obscure cases where it was needed, <tt>weaklinkdeps</tt> and <tt>entry</tt> objects can be used instead.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-25T03:04:48Z

BAILOPAN: /* Changes from 2.1 */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed. In the obscure cases where it was needed, <tt>weaklinks</tt> and <tt>entry</tt> objects can be used instead.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-25T03:04:07Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.

''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.
* The <tt>Dep</tt> API has been removed, since it is fully replaced (more conveniently, even) by other means.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-25T02:41:42Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''include_hotlist'' - Array of important headers. This is unused by AMBuild, but when generating IDE project files, the named includes will show up in the project explorer.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-24T23:28:10Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either 'msvc', 'gcc', 'clang', or 'emscripten'.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either 'msvc' or 'gcc'.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-24T15:18:38Z

BAILOPAN: /* Precompiled Headers */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

Also note, a <tt>PrecompiledHeaders</tt> builder does not support modules or custom tools.

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-24T04:26:01Z

BAILOPAN: /* Methods */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly. This is intended for small text files, since the data is stored directly in the internal database.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-24T04:02:30Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''AddOutputFile(path, contents)'' - Adds a task that causes contents to be written to path. The file is always opened in binary mode, and the data given as contents should be a <tt>bytes</tt> object when using Python 3. Python 2 will accept a <tt>str</tt>, but it's highly recommended that you call the <tt>encode</tt> function to make sure it is encoded properly.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The <tt>source_type</tt> argument must be 'c' or 'c++'. See the [[#Precompiled Headers]] section for more information.</tt>
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', source_type = 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

The <tt>source_type</tt> argument must be either 'c' or 'c++', depending on what kind of files will be including it. GCC does not support mixing and matching and AMBuild will ignore it with a warning.

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-24T03:40:40Z

BAILOPAN: /* Precompiled Headers */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The builder is configured to produce a precompiled header object for each source input. When added to a builder, it returns a <tt>PchNodes</tt> object, which can be added to the <tt>includes</tt> (or <tt>cxxincludes</tt>) of another <tt>BinaryBuilder</tt>. The <tt>source_type</tt> argument must be 'c' or 'c++'. Make sure that when using precompiled headers, the exact same compiler and architecture flags are used, and that C source files never use C++ precompiled headers (and vice versa).
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild provides a unified header that can be used as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-24T03:39:56Z

BAILOPAN: /* Precompiled Headers */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The builder is configured to produce a precompiled header object for each source input. When added to a builder, it returns a <tt>PchNodes</tt> object, which can be added to the <tt>includes</tt> (or <tt>cxxincludes</tt>) of another <tt>BinaryBuilder</tt>. The <tt>source_type</tt> argument must be 'c' or 'c++'. Make sure that when using precompiled headers, the exact same compiler and architecture flags are used, and that C source files never use C++ precompiled headers (and vice versa).
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild attempts to bridge the common functionality together.

When using a <tt>PrecompiledHeaders</tt> builder, the source files should be header files (.h, .hpp, or .hxx). AMBuild will generate a unified header combining these together. For example,

<python>
pch_builder = cxx.PrecompiledHeaders('myheaders', 'c++')
pch_builder.sources += [
'amtl/am-vector.h',
'amtl/am-string.h',
]
pch = builder.Add(pch_builder)
</python>

To use this in a subsequent C++ project, simply add it to <tt>includes</tt> or <tt>cxxincludes</tt>:

<python>
binary = cxx.Program('hello')
binary.cxxincludes += [pch]
</python>

The position doesn't matter. AMBuild will automatically position precompiled header includes to the front of the final list.

In your C++ source, precompiled header includes must come before any C/C++ tokens. AMBuild builds a wrapper header that can be included as follows:

<cpp>
#include <myheaders.h>
</cpp>

Note that the name "myheaders.h" is derived from the <tt>PrecompiledHeaders</tt> builder name.

Precompiled headers are easy to misuse, and errors can be extremely difficult to detect. AMBuild makes no attempt to ensure they're being used correctly. In particular:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it. Exactly what must match is compiler dependent, so it's best to use the same settings everywhere.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler and will silently ignore the precompiled headers.</li>
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-23T21:38:25Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The builder is configured to produce a precompiled header object for each source input. When added to a builder, it returns a <tt>PchNodes</tt> object, which can be added to the <tt>includes</tt> (or <tt>cxxincludes</tt>) of another <tt>BinaryBuilder</tt>. The <tt>source_type</tt> argument must be 'c' or 'c++'. Make sure that when using precompiled headers, the exact same compiler and architecture flags are used, and that C source files never use C++ precompiled headers (and vice versa).
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Precompiled Headers=
Clang, GCC, and MSVC all support some notion of precompiled headers, but the level of support and compatibility between them is wildly different. AMBuild supports this feature, but makes no attempts to ensure that you're using them correctly. To ensure that they will work, we recommend the following:
<ul>
<li>Make sure the compiler settings (especially, architecture, version, and flags) are identical between the <tt>PrecompiledHeaders</tt> object and builders that depend on it.</li>
<li>Always use include guards in precompiled headers. Do not use <tt>#pragma once</tt> because GCC has long-standing, unfixed bugs around using it with precompiled headers.</li>
<li>Make sure the <tt>#include</tt> directive for a precompiled header is the very first thing in your source files. Preceding C/C++ tokens will confuse the compiler.</li>
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-23T19:16:36Z

BAILOPAN: /* Methods */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The builder is configured to produce a precompiled header object for each source input. When added to a builder, it returns a <tt>PchNodes</tt> object, which can be added to the <tt>includes</tt> (or <tt>cxxincludes</tt>) of another <tt>BinaryBuilder</tt>. The <tt>source_type</tt> argument must be 'c' or 'c++'. Make sure that when using precompiled headers, the exact same compiler and architecture flags are used, and that C source files never use C++ precompiled headers (and vice versa).
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-23T19:15:23Z

BAILOPAN: /* Methods */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>PrecompiledHeaders(name, source_type)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler's settings. The builder is configured to produce a precompiled header object for each source input. When added to a builder, it returns a <tt>PchNodes</tt> object, which can be added to the <tt>includes</tt> (or <tt>cxxincludes</tt>) of another <tt>BinaryBuilder</tt>.
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-23T18:08:51Z

BAILOPAN: /* C++ Detection */

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

On Linux, true cross-compilation (eg something like x86 to ARM) is automatically detected for Debian-derived distributions. For example, if the target is "linux-arm-gnueabihf", AMBuild will automatically search for a compiler named "arm-linux-gnueabihf-gcc".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild

2020-08-23T07:54:31Z

BAILOPAN: /* Requirements */

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback (see the bottom of this page) if you use it in your own projects.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 2.7 or higher is required. If using Python 3, then 3.3 or higher is required.

Additionally, pip and setuptools (both Python components) are also required. If your distribution or Python installation does not provide for these, see [https://pip.pypa.io/en/stable/installing/ Installing Pip] for manual instructions.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: By default, pip will perform per-user installations. To install globally for all users, you will need to use "sudo" (or run as Administrator on Windows).

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. The author is not aware of an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

==Tup==
AMBuild is designed to be, essentially, a miniature clone of Tup written entirely in Python. In particular it closely follows concepts in [http://gittup.org/tup/build_system_rules_and_algorithms.pdf the Tup whitepaper]. However there are a few differences that may make one more desirable over the other:
* Tup has been around longer than AMBuild 2, and has been more thoroughly tested.
* Tup uses complex file system features to optimize updates. Algorithms that are O(n) in AMBuild tend to be O(1) in Tup.
* AMBuild only requires a default Python installation to work. Tup, due to being written in C and using very platform specific file system features, may not be as accessible.
* Tup has more features for speeding up very large projects. It can do minimal reparsing and it can reduce the number of links in large graphs.
* AMBuild is designed to be a front-end in addition to a back-end. It has a simple API and script syntax, and is designed to support multiple output formats. For example, it could conceivably generate Visual Studio or XCode project files.

Since AMBuild is also a frontend, AMBuild may one day eliminate its backend in favor of emitting Tupfiles instead.

AMBuild's IPC implementation is very low-level, and it has not yet been ported beyond Windows, Mac/BSD, or Linux. However it's not difficult to port to Unix-like systems, and if needed a generic (albeit suboptimal) cross-platform implementation could be provided.

AMBuild

2020-08-23T07:53:52Z

BAILOPAN: /* Requirements */

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback (see the bottom of this page) if you use it in your own projects.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 2.7 or higher is required. If using Python 3, then 3.3 or higher is required.

Two Python components, pip and setuptools, are also required. If your distribution does not provide packages for these, see [https://pip.pypa.io/en/stable/installing/ Installing Pip] for manual instructions.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: By default, pip will perform per-user installations. To install globally for all users, you will need to use "sudo" (or run as Administrator on Windows).

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. The author is not aware of an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

==Tup==
AMBuild is designed to be, essentially, a miniature clone of Tup written entirely in Python. In particular it closely follows concepts in [http://gittup.org/tup/build_system_rules_and_algorithms.pdf the Tup whitepaper]. However there are a few differences that may make one more desirable over the other:
* Tup has been around longer than AMBuild 2, and has been more thoroughly tested.
* Tup uses complex file system features to optimize updates. Algorithms that are O(n) in AMBuild tend to be O(1) in Tup.
* AMBuild only requires a default Python installation to work. Tup, due to being written in C and using very platform specific file system features, may not be as accessible.
* Tup has more features for speeding up very large projects. It can do minimal reparsing and it can reduce the number of links in large graphs.
* AMBuild is designed to be a front-end in addition to a back-end. It has a simple API and script syntax, and is designed to support multiple output formats. For example, it could conceivably generate Visual Studio or XCode project files.

Since AMBuild is also a frontend, AMBuild may one day eliminate its backend in favor of emitting Tupfiles instead.

AMBuild's IPC implementation is very low-level, and it has not yet been ported beyond Windows, Mac/BSD, or Linux. However it's not difficult to port to Unix-like systems, and if needed a generic (albeit suboptimal) cross-platform implementation could be provided.

AMBuild

2020-08-23T07:52:15Z

BAILOPAN: /* Installation */

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback (see the bottom of this page) if you use it in your own projects.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 2.7 or higher is required. If using Python 3, then 3.3 or higher is required.

PIP and Setuptools are also required, these two packages are technically optional in the Python universe and '''''MAY''''' require manual installation. Some Linux (example: Ubuntu/Debian) platforms provide packages to install pip and setuptools while the Windows Python installer bundles a copy of PIP & Setuptools, otherwise, the generic way is via [https://bootstrap.pypa.io/get-pip.py get-pip.py] with no arguments.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: By default, pip will perform per-user installations. To install globally for all users, you will need to use "sudo" (or run as Administrator on Windows).

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. The author is not aware of an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

==Tup==
AMBuild is designed to be, essentially, a miniature clone of Tup written entirely in Python. In particular it closely follows concepts in [http://gittup.org/tup/build_system_rules_and_algorithms.pdf the Tup whitepaper]. However there are a few differences that may make one more desirable over the other:
* Tup has been around longer than AMBuild 2, and has been more thoroughly tested.
* Tup uses complex file system features to optimize updates. Algorithms that are O(n) in AMBuild tend to be O(1) in Tup.
* AMBuild only requires a default Python installation to work. Tup, due to being written in C and using very platform specific file system features, may not be as accessible.
* Tup has more features for speeding up very large projects. It can do minimal reparsing and it can reduce the number of links in large graphs.
* AMBuild is designed to be a front-end in addition to a back-end. It has a simple API and script syntax, and is designed to support multiple output formats. For example, it could conceivably generate Visual Studio or XCode project files.

Since AMBuild is also a frontend, AMBuild may one day eliminate its backend in favor of emitting Tupfiles instead.

AMBuild's IPC implementation is very low-level, and it has not yet been ported beyond Windows, Mac/BSD, or Linux. However it's not difficult to port to Unix-like systems, and if needed a generic (albeit suboptimal) cross-platform implementation could be provided.

AMBuild

2020-08-23T07:50:57Z

BAILOPAN: /* Requirements */

AMBuild is a tool for building software projects and creating release packages. It is targeted at C++ projects, though it can be used for anything. It has been tailored to solve three major problems that most build tools do not address:
*'''Accuracy'''. You should *never* need to clean a build. Clean rebuilds are unnecessary and a waste of your time. AMBuild always computes minimal rebuilds accurately - any failure to do so is considered a bug.
*'''Speed'''. Most build systems need to traverse the entire dependency graph for changes. AMBuild only needs to look at the set of changed files on the filesystem.
*'''Flexibility'''. Build scripts are written in Python, so they're very easy to write and provide full programmatic control.

Keep in mind, AMBuild is neither widely used nor has it been used on a wide variety of systems. AlliedModders has used it successfully for small to medium-sized C++ projects on Linux, Mac, and Windows. Our largest project, SourceMod, has 700 C++ files and over 200,000 lines of code. We're happy to receive feedback (see the bottom of this page) if you use it in your own projects.

=Motivation=

AlliedModders C++ projects require a lot of customization. The set of flags passed to the compiler, their order, how things get linked, is all delicate and complicated. In addition, each Source game requires different linkage, so our C++ files usually get compiled multiple times, over and over again, into separate binaries. Lastly, our projects are large, and minimizing build time through correct dependency computation and parallelization is important. Very few build systems can handle any of these scenarios well, much less all of them, so we sought to make a new build system.

The initial version of AMBuild only solved flexibility problems. By controlling the build pipeline through Python, we were able to generate 15+ different binaries from the same source files without any code duplication. Over time the AMBuild script syntax has become very simple; you no longer need a complex project to justify AMBuild.

The modern version of AMBuild (also known as AMBuild 2), is modeled after [http://gittup.org/tup/ Tup]. Tup is a huge advance forward in build systems, and it is likely that one day AMBuild will simply use Tup as a backend. If you are looking at AMBuild as a build platform for your projects, you may want to see whether Tup meets your needs instead.

=Requirements=

Python 2.7 or higher is required. If using Python 3, then 3.3 or higher is required.

PIP and Setuptools are also required, these two packages are technically optional in the Python universe and '''''MAY''''' require manual installation. Some Linux (example: Ubuntu/Debian) platforms provide packages to install pip and setuptools while the Windows Python installer bundles a copy of PIP & Setuptools, otherwise, the generic way is via [https://bootstrap.pypa.io/get-pip.py get-pip.py] with no arguments.

AMBuild has been tested to work on the following platforms. Although builds of Python for specific architectures were tested, we expect that other architectures will work as well.
* Windows 7+ with x86, x86_64, arm, or arm64 targets.
* Linux with clang and GCC.
* OS X 10.9+ with x86 and x86_64 targets.

It has also been tested to work with the following compilers:
* Visual Studio 2015+
* GCC 4+
* Clang 3+
* Emscripten 1.25+ (JS output mode only, lib deps do not work)

=Installation=

AMBuild can be downloaded via GitHub at [https://github.com/alliedmodders/ambuild https://github.com/alliedmodders/ambuild].

<pre>
$ git clone https://github.com/alliedmodders/ambuild
$ pip install ./ambuild
</pre>

Note: Administrator privileges are required to install AMBuild for '''''ALL USERS''''', otherwise, pip will install AMBuild at the user level.

=Tutorial=

See the [[AMBuild Tutorial]] for more information.

=API=

See the [[AMBuild API]] article for more information.

=Technical Overview=

AMBuild is separated into a ''frontend'' and a ''backend''. The frontend is responsible for parsing build scripts (this is known as the ''configure'' step). The backend is responsible for actually performing builds. The frontend and backend are separate, and it is possible to use a different backend other than AMBuild. For example, there are plans for the configure step to be able to produce Visual Studio project files.

== Configuring ==

Build scripts are written in Python, and they are parsed whenever you configure the build. If a build script changes, it will automatically re-trigger the configure process on the next build. When a configure takes place, any files left by an old build are removed if they are modified or removed in the new dependency graph.

The details of the generated dependency graph are stored in an SQLite database, which is located in a hidden <tt>.ambuild2</tt> folder inside the build path.

== Building ==

The build process involves a few important steps that are executed every time you use the <tt>ambuild</tt> command:
<ol>
<li>'''Damage Computation'''. Builds a list of all files that have changed since the last build. This is based on filesystem timestamps, and either a forward or backward time change is enough to be considered "damaged" (or dirty). For example:
<pre>
$ ambuild --show-changed
/home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Partial DAG Construction'''. A partial dependency graph is built based on the list of damaged files. This is the entire set of nodes in the graph which need to be recomputed. The output of this step can be seen with <tt>--show-damage</tt>. For example:
<pre>
$ ambuild --show-damage
- package/addons/metamod/bin/server_i486.so
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- loader/server_i486/server_i486.so
- c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server_i486.so
- loader/server_i486/loader.o
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
- /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp
</pre>
</li>
<li>'''Task Construction'''. The partial DAG is simplified into a tree of commands to run. The output of this step can be seen with <tt>--show-commands</tt>. For example:
<pre>
$ ambuild --show-commands
- cp "../loader/server_i486/server_i486.so" "package/addons/metamod/bin/server_i486.so"
- c++ loader.o gamedll.o serverplugin.o utility.o -shared -o server_i486.so
- [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
</pre>
</li>
<li>'''Updating'''. Each task in the task tree is executed and the results are processed to either reject the build, or update the state of the dependency graph. At this phase, tasks are executed in parallel based on the number of CPU cores available. The task graph is also shared to maximize throughput. You can see the sequential build steps with <tt>--show-steps</tt>:
<pre>
$ ambuild --show-steps
task 0: [gcc] -> c++ -Wall -Werror -H -c /home/dvander/alliedmodders/mmsource-central/loader/loader.cpp -o loader.o
-> loader/server/loader.o
task 1: c++ loader.o gamedll.o serverplugin.o utility.o -m32 -static-libgcc -shared -o server.so
-> loader/server/server.so
task 2: cp "../loader/server/server.so" "package/addons/metamod/bin/server.so"
-> package/addons/metamod/bin/server.so
</pre>
Maximizing throughput in Python is tricky since it has limited capability for IPC and multithreading. AMBuild spawns worker processes based on the number of CPUs available, which run task jobs and return the results.
</li>
</ol>

=Comparisons=
==Make, Speed==
Make uses a recursive update scheme. Starting with the top-level rule, Make will recursively search all dependencies to find outdated rules, and it will update all rules as it unwinds. This usually involves touching way more rules than are necessary. Consider the following dependency graph:

[[Image:RecursiveDepGraph.png]]

In this graph, <tt>stdint.h</tt> has been modified. Even though it's the only rule that has been changed, Make must visit every single node in the graph to discover that it has changed. Furthermore, it has to visit it multiple times: once for <tt>main.o</tt>, and another time for <tt>helpers.o</tt>. In a large dependency graph, this is very expensive.

In AMBuild, the direction of the graph is reversed:

[[Image:AMDepGraph.png]]

With this graph, it is possible to visit every node once. Once we know that <tt>stdint.h</tt> has changed, we can follow the edges upward and ignore everything in the graph that is unaffected:

[[Image:AMPartialDepGraph.png]]

==Make, Accuracy==
AMBuild strives to be accurate by design, in two ways:
* Computation of dependencies should be as minimally accurate as possible. Changing a build script should not result in a complete rebuild.
* An incremental build should be exactly the same as a fresh build.

It is difficult to achieve very accurate rebuilds in Make. For example, consider a Makefile that lists source files and CFLAGS, and invokes the C++ compiler to build and link them:
<pre>
# Makefile
CFLAGS = -Wall

helpers.o: helpers.cpp
$(CC) $(CFLAGS) helpers.cpp -c -o helpers.o
main.o: main.cpp
$(CC) $(CFLAGS) main.cpp -c -o main.o

main: main.o helpers.o
$(CC) main.o helpers.o -o main
</pre>

If you change <tt>helpers.cpp</tt>, you will get a minimal rebuild. If you add a new source file, you will likely get a minimal rebuild. However, if you ''remove the <tt>helpers</tt> rule completely'', the build will be incorrect, because <tt>Make</tt> cannot tell that <tt>main</tt> needs to be relinked.

One way to solve this is to have certain rules, like the link rule, have a dependency on <tt>Makefile</tt> itself. But then if you change <tt>CFLAGS</tt>, it will trigger a relink, even though that rule does not depend on <tt>CFLAGS</tt>. You would need to break the Makefile down into many smaller Makefiles.

AMBuild mitigates these problems by intelligently updating the dependency graph. If a reparse of the build scripts produces identical nodes, it will not consider those nodes as stale.

Furthermore, when deleting rules, Make will leave their outputs behind. The author is not aware of an easy way to solve this. Leaving old outputs behind is undesirable for a number of reasons. Stale outputs might fool a user or developer tool into thinking the build has succeeded, when in fact it has failed. Stale outputs might be loaded accidentally, i.e. <tt>LD_LIBRARY_PATH</tt> picking up a library that should not exist. Tests that developers forgot to update might pass locally because of a stale output.

In AMBuild, leaving stale files behind is an error, since they would not be produced by a fresh build.

==Tup==
AMBuild is designed to be, essentially, a miniature clone of Tup written entirely in Python. In particular it closely follows concepts in [http://gittup.org/tup/build_system_rules_and_algorithms.pdf the Tup whitepaper]. However there are a few differences that may make one more desirable over the other:
* Tup has been around longer than AMBuild 2, and has been more thoroughly tested.
* Tup uses complex file system features to optimize updates. Algorithms that are O(n) in AMBuild tend to be O(1) in Tup.
* AMBuild only requires a default Python installation to work. Tup, due to being written in C and using very platform specific file system features, may not be as accessible.
* Tup has more features for speeding up very large projects. It can do minimal reparsing and it can reduce the number of links in large graphs.
* AMBuild is designed to be a front-end in addition to a back-end. It has a simple API and script syntax, and is designed to support multiple output formats. For example, it could conceivably generate Visual Studio or XCode project files.

Since AMBuild is also a frontend, AMBuild may one day eliminate its backend in favor of emitting Tupfiles instead.

AMBuild's IPC implementation is very low-level, and it has not yet been ported beyond Windows, Mac/BSD, or Linux. However it's not difficult to port to Unix-like systems, and if needed a generic (albeit suboptimal) cross-platform implementation could be provided.

AMBuild API

2020-08-23T07:46:17Z

BAILOPAN:

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API

2020-08-23T07:46:04Z

BAILOPAN: BAILOPAN moved page AMBuild API (2.2) to AMBuild API

This documentation is for the AMBuild 2.2 API. See older versions: [[AMBuild API (2.1)]] or [[AMBuild API (2.0)]].

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''build context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''Project''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and four-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>argparse.ArgumentParser</tt>.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is "objdir". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

Custom attributes can be set on Build Contexts. When evaluating nested build scripts, these attributes will be automatically copied. If the object stored at the attribute inherits from <tt>ambuild2.frontend.cloneable.Cloneable</tt>, then it will be deep copied. Compiler objects (described later on) are always cloned this way, so nested build scripts do not interfere with parent ones.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(**kwargs)'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the options available, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and Projects return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.
* ''HasFeature(name)'' - Returns whether the given named feature is available. This is not currently used, but exists so we can extend the API in a backwards-compatible way in the future.
* ''ProgramProject(name)'' - Returns a <tt>Project</tt> for building executable programs. Projects are described later on.
* ''LibraryProject(name)'' - Returns a <tt>Project</tt> for building dynamically linked libraries. Projects are described later on.
* ''StaticLibraryProject(name)'' - Returns a <tt>Project</tt> for building statically linked libraries. Projects are described later on.
* ''CloneableList(*args, **kwargs)'' - Wrapper around <tt>list</tt> that implements <tt>Cloneable</tt>. This can be used to make lists that are deep-copied when assigned to an attribute in a build context.
* ''CloneableDict(*args, **kwargs)'' - Wrapper around <tt>OrderedDict</tt> that implements <tt>Cloneable</tt>. This can be used to make dictionaries that are deep-copied when assigned to an attribute in a build context.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

Some patterns are normalized when passed as arguments. For example, "amd64" or "x64" will be normalized to "x86_64" for convenience.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.
* ''target'' - Returns the <tt>System</tt> object representing the platform and architecture tuple. Currently, AMBuild has support for cross-compiling to different architectures, but not to different platforms, so the platform will always match <tt>builder.host.platform</tt>.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=Project=
Projects assist in creating multiple configurations of a C++ compilation task. It is essentially a factory for <tt>BinaryBuilders</tt>. It's useful for tying multiple configurations of the same basic component together. The build output is identical to using <tt>BinaryBuilder</tt>. However, when used with Visual Studio project file generation, you will get one vcxproj file instead of many. Therefore, it's helpful for organization when using AMBuild's IDE tooling.

<tt>Project</tt> instances can be obtained through the build context, via <tt>ProgramProject</tt>, <tt>LibraryProject</tt>, and <tt>StaticLibraryProject</tt>. You can set the source list via the <tt>sources</tt> attribute, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(compiler, name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The compiler must be an object returned by <tt>builder.DetectCxx()</tt>. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>On Windows, if <tt>AMBUILD_VCVARS_<arch></tt> is defined in the environment,
AMBuild will use the .bat file specified to create the Visual Studio environment.
The <tt><arch></tt> component can either be a normalized architecture name
(such as <tt>X86_64</tt>) or it can be <tt>ALL</tt>, in which case, the VS architecture
name will be passed to the batch file as an argument.</li>
<li>On Windows, AMBuild then looks in the registry for Visual Studio 2015. It will
also look for the 'vswhere' tool, and if present, will detect installations
of Visual Studio 2017 and 2019. The highest working version is used. It will
also detect Microsoft Visual C++ Build Tools (2015). If no working version
of anything is found, the logic in step 2 is used as a last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

In all cases, if <tt>CFLAGS</tt> and/or <tt>CXXFLAGS</tt> are defined in the environment,
they will be propagated into the detected compiler.

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure Windows Kit 10 properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand via <tt>AMBUILD_VCVARS</tt>.

==Cross Compilation==
AMBuild tries to automatically detect cross-compilation, eg, compiling to non-native triple.
A triple is a platform-arch[subarch][-abi] sequence. For example, windows-x86 or
linux-armv7-gnueabihf. On Mac and Windows targets, the ABI part of the triple is always
dropped since there is only one ABI.

These triples directly correspond to <tt>System</tt> objects.

When specifying targets via a triple, AMBuild supports some shorthand sequences:
* arch will only change the target architecture. Eg, "x86" on "linux-x86_64" will result in "linux-x86".
* platform-arch works when the ABI can be elided. Eg, "windows-x86".
* arch-abi works when the host and target platform are the same. Eg, "arm-gnueabihf" on "linux-x86" will result in "linux-arm-gnueabihf".

==Options==
As of AMBuild 2.2, <tt>builder.DetectCxx()</tt> supports the following options. Options not recognized are ignored.
<ul>
<li><tt>target</tt> - A string to force the compiler's triple (or shorthand for a triple), as described above. Normally, AMBuild will use the first working compiler it can find, which could theoretically have any target configuration. This will force AMBuild to find a matching compiler, and if none exists, it will fail.</li>
<li><tt>target_arch</tt> - A string to force only a change in architecture. This is useful for projects that do not support cross-platform, but do support cross-architecture, builds.</li>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.1=
* <tt>Context.cxx</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt> if you do not support multi-architecture builds.
* The <tt>target</tt> field on Contexts has been moved to the <tt>Compiler</tt> object.
* Projects may no longer be created from <tt>Compiler</tt> objects. They are created from contexts, and compilers are attached when a project binary is created.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been removed. You can set it manually after calling <tt>DetectCxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>host_platform</tt> field on Contexts has been replaced with the <tt>host</tt> System object. It is enough to replace <tt>host_platform</tt> with <tt>host.platform</tt>.
* The <tt>target_platform</tt> field on Contexts has been moved to the <tt>Compiler</tt> object. It's now a <tt>System</tt> object and has been renamed to <tt>target</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.
* The <tt>BuildParser.options</tt> field is now an <tt>argparse.ArgumentParser</tt>, rather than an <tt>optparse.OptionParser</tt>.

AMBuild API (2.2)

2020-08-23T07:46:04Z

BAILOPAN: BAILOPAN moved page AMBuild API (2.2) to AMBuild API

#REDIRECT [[AMBuild API]]

AMBuild API (2.1)

2020-08-23T07:45:42Z

BAILOPAN: BAILOPAN moved page AMBuild API to AMBuild API (2.1) over redirect

This documentation is for the AMBuild 2.1 API. [[AMBuild API (2.0)|Click here]] for the 2.0 API.

AMBuild scripts have access to the following object types:
* '''BuildParser''': This tells AMBuild how to begin parsing your <tt>AMBuildScript</tt>. It is usually created in <tt>configure.py</tt>.
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''configure context''.
* '''Entry''': Represents a node in the dependency graph.
* '''Compiler''': An abstraction representing a C++ compiler environment.
* '''ProjectBuilder''' and '''BinaryBuilder''': Abstractions for building C++ compilation jobs.

As a general rule, AMBuild uses the following conventions:
* Methods starting with an upper-case letter are considered public API.
* Methods starting with a lower-case letter are considered private and should not be used. There are a few exceptions for brevity or accessor-like functions.
* Properties and attributes ending with an underscore are considered private and should not be used.
* Spaces are used instead of tabs, and two-space indents are preferred.

=BuildParsers=

BuildParsers are created in <tt>configure.py</tt>, and the final step of <tt>configure.py</tt> is to call <tt>parser.Configure()</tt>, which will begin parsing the root <tt>AMBuildScript</tt> of the project. BuildParsers have extra properties worth exploring for more complicated projects:
* <tt>options</tt> - An instance of <tt>optparse.OptionParser</tt>. Note that AMBuild can run on either Python 2 or Python 3, so it is best to use the subset which is common to both versions.
* <tt>host</tt> - The System object for the host system. (see [[#Platforms]])
* <tt>default_build_folder</tt> - By default, the build folder for a project is a string constructed out of the platform and architecture, such as "obj-linux-i386". This property can be set to change the default. It can be a string, or a function taking a <tt>BuildParser</tt> object and returning a string.
* <tt>target_arch</tt> - If this project only supports a single target architecture, it may be specified here. Otherwise, the target architecture will be inherited from the host architecture, and can be further overridden by the <tt>--target-arch</tt> command-line option.
* <tt>default_arch</tt> - By default, this is <tt>None</tt>. A project can set this to a default architecture if it prefers one. <tt>--target-arch</tt> will still override it if specified.

Note that architectures specified on the command line are currently not normalized - they are passed as given.

=Contexts=

Contexts are implemented in <tt>ambuild2/frontend/base_gen.py</tt>. They are the entry point for using AMBuild.

When using path strings, it is important to note how AMBuild recognizes paths.
* ''source'' path strings may be any absolute path in the file system, as long as that path is not within the build folder. Source paths may also be expressed as relative to <tt>builder.currentSourcePath</tt>, which is the source folder of the currently executing build script.
* ''output'' path strings are always relative to <tt>builder.buildFolder</tt>.

==Attributes==
* ''cxx'' - An instance of a <tt>Compiler</tt> object, or <tt>None</tt> if <tt>DetectCxx</tt> was never called. Calling <tt>DetectCxx</tt> will set the <tt>compiler</tt> field for this and all future contexts. Each context gets a clone of its parent's compiler, so it is safe to modify compilers in inner scripts.
* ''parent'' - The context that loaded the current context.
* ''script'' - The path, relative to <tt>sourcePath</tt>, of the current build script.
* ''sourcePath'' - The absolute path to the source tree.
* ''options'' - The result of evaluating command-line options from <tt>configure.py</tt>, via the <tt>optparse</tt> module.
* ''buildPath'' - The absolute path to the build folder.
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
* ''localFolder'' - The <tt>Entry</tt> for <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
* ''currentSourcePath'' - The source folder that the current build script is in.
* ''target'' - The System object corresponding to the desired target system (see [[#Platforms]]).
* ''host'' - The System object corresponding to the host system (see [[#Platforms]]).
* ''originalCwd'' - The working directory that was set when the user first configured the build. This is useful when constructing absolute paths from user inputs that contain relative paths.

==Methods==
* ''SetBuildFolder(folder)'' - Sets the working directory of jobs in this context, relative to <tt>buildPath</tt>.
** ''folder'' - A string representing the folder path. '.' and './' are allowed.
** Returns <tt>None</tt>.
* ''DetectCxx(options = {})'' - Detects C and C++ compilers and raises an exception if neither are available or they do not match. The full rules for this, and the <tt>options</tt> dictionary, are under [[#C++ Detection]].
** Returns a <tt>Compiler</tt> object that is also accessible via the <tt>compiler</tt> attribute.
* ''Add(taskbuilder)'' - Some jobs are too complex to use a single API call, and instead provide objects to assist in creation. These objects are finalized into the dependency graph with this function. Currently, the only complex jobs built-in are C/C++ compilation jobs.
** ''taskbuilder'' - The job builder instance.
** Returns a value based on the taskbuilder. For example, BinaryBuilders return a 'CppNode' described under the Compiler section, and ProjectBuilders return a list of CppNodes.
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
** ''folder'' - A relative path specifying the folder. Folder chains can be created all at once; i.e. 'a/b/c' is a valid target even if 'a' or 'a/b' do not exist.
** Returns an <tt>Entry</tt> instance describing the folder creation node.
* ''AddSymlink(source, output_path)'' - Adds a job to the build that will perform a symlink. On systems where symlinks are not available, it is implemented as a copy.
* ''AddCopy(source, output_path)'' - Adds a job to the build that will perform a file copy.
** ''source'' - Either a string containing a source file path, or a source node, or an output node, representing the file that will be the source of the operation.
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, specifying the folder to copy or symlink the file to. It is relative to the context's local build folder.
*** A string path ending in a filename, representing the destination file of the operation. It is relative to the context's local build folder.
*** A folder node created via <tt>AddFolder()</tt>, representing the folder to copy or symlink the file to. In this case, the folder node's path is taken as-is and is not relative to the local build folder.
** See <tt>AddCommand</tt> for return values.
* ''AddCommand(inputs, argv, outputs, folder?, dep_type?, weak_inputs?, shared_outputs?)'' - Adds a custom command that will be executed manually. The working directory of the command is the context's local build folder. As created, the command has no dependencies. If it has source dependencies they can be specified via <tt>AddDependency</tt>.
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
** ''outputs'' - An iterable containing files that are outputs of this command. Each file must be a relative path from the context's local build folder.
** ''folder'' - The working directory for the command. By default, this is <tt>buildFolder</tt>. It can be <tt>None</tt> to specify the root of the build. Otherwise, it must be an <tt>Entry</tt> from calling <tt>AddFolder</tt> or reading <tt>localFolder</tt>.
** ''dep_type'' - Specifies whether the output of the command contains a dependency list. The following three values are supported:
*** <tt>None</tt> - (default) This command does not support dependency discovery or does not have dynamic dependencies.
*** <tt>'msvc'</tt> - Dependencies are spewed in the exact manner of the Visual Studio C++ compiler, in <tt>stdout</tt>.
*** <tt>'gcc'</tt> - Dependencies are spewed in the exact manner of the GNU C Compiler or Clang, in <tt>stderr</tt>.
*** <tt>'sun'</tt> - Dependencies are spewed in the exact manner of the Sun Pro compiler, in <tt>stderr</tt>.
*** <tt>'fxc'</tt> - Dependencies are spewed in the exact manner of the FXC compiler, in <tt>stdout</tt>.
** ''weak_inputs'' - Optional list of weak dependencies. Weak dependencies enforce an ordering between two commands, but an update only occurs if the command is discovered to actually use the dependency (see the Compiler.sourcedeps attribute).
** ''shared_outputs'' - Optional list of "shared" outputs. Shared outputs are files that are generated by multiple commands. This is a degenerate case in AMBuild, but some systems do this, and AMBuild needs to understand where the files came from. Shared outputs can not be used as an input; they do not participate in the dependency system, except that AMBuild knows when to remove them.
** Returns a 2-tuple, containing:
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.
* ''AddConfigureFile(path)'' - Adds a source path that will trigger automatic reconfiguring if the file changes. This is useful for files that are conceptually part of a build script, but are not actually loaded as a build script.
** ''path'' - A source path.

===Contexts and Scripts===

AMBuild can run additional, user-provided scripts so the build process is not clumped into one giant file. When running sub-scripts, each script has a "context". This context is a sub-builder that inherits various properties, and allows the script to not potentially interfere with variables and state in the global builder. These contexts can be created in one of three ways:
* '''Child''' contexts are relative to the context that created them. Their containing folder must be the parent folder or a folder somewhere underneath it, and their output folder is always the parent's output folder or a sub-folder of it.
* '''Top-Level''' contexts are child contexts that have no parent; they can change their output folder.
* '''Empty''' contexts have no input or output folder; they cannot perform build steps in their own context.

With that in mind, AMBuild provides the following functions on build contexts to assist in running additional scripts. Each of these functions takes in an optional ''vars'' parameter; if not provided, it is initialized to an empty <tt>dict</tt>. Otherwise the newly run script's globals will be merged with ''vars'', along with the ''vars'' used to call the invoking script (if any).

Additionally, each of these methods accepts a ''path'' (or in some cases, a list of paths). These paths must either be relative to the current source folder, or they may be specified as relative to the root of the source tree via a leading '/'. Paths may not be outside the source tree.

* ''Import(path, vars?)'' - Runs ''path'' in an empty context, and returns the globals of the completed script as a <tt>dict</tt>. If ''path'' is not a string, and is iterable, each path will be run in iteration order and <tt>None</tt> will be returned.
* ''Eval(path, vars?)'' - Helper function that runs ''path'' in an empty context, and returns the value of the global variable <tt>rvalue</tt> in the completed script (or <tt>None</tt> if none was present).
* ''Build(path, vars?)'' - Runs ''path'' in a child context. ''path'' may alternately be an iterable of path strings, in which case each is evaluated in iteration order. If ''path'' is a single path string, and the executed script ends with a global variable called ''rvalue'', then the value of that variable is returned. Otherwise, <tt>None</tt> is returned.

==Platforms==
AMBuild represents the host and target system via System objects. These objects have <tt>platform</tt> and <tt>arch</tt> properties. <tt>platform</tt> may be one of:
* <tt>"windows"</tt>
* <tt>"mac"</tt>
* <tt>"linux"</tt>
* <tt>"freebsd"</tt>
* <tt>"openbsd"</tt>
* <tt>"netbsd"</tt>
* <tt>"solaris"</tt>
* <tt>"cygwin"</tt>

<tt>arch</tt> may be one of:
* <tt>"x86_64"</tt>
* <tt>"x86"</tt>
* <tt>"arm64"</tt>
* <tt>"armv*"</tt> (where * is the ARM version and configuration, such as "armv5ejl")
* ... Other architectures are untested, but will be added here as tested.

The target architecture represents what the build should attempt to configure itself for. AMBuild does not attempt to configure the compiler or environment for cross-compiling.

=Entry=
<tt>Entry</tt> objects are considered mostly opaque. However, all frontends must define at least these attributes:
* ''path'' - A file system path that uniquely represents nodes that are present in the filesystem, such as source files, output files, or folders.

=Compiler=
Compiler objects encapsulate information about invoking the C or C++ compiler. Most of its attributes are lists of options, so it is best to use += to extend these lists, to avoid replacing previously set options.

Whenever options come in pairs - for example, C/C++ flags versus C++-only flags, C++ flags will automatically include all C flags during compilation time.

==Attributes==
* ''includes'' - List of C and C++ include paths
* ''cxxincludes'' - List of C++ include paths.
* ''cflags'' - List of C and C++ compiler flags.
* ''cxxflags'' - List of C++ compiler flags.
* ''defines'' - List of C and C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''cxxdefines'' - List of C++ #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''rcdefines'' - List of RC (Resource Compiler) #defines, in the form of 'KEY' or 'KEY=VALUE'
* ''linkflags'' - Link flags (see below).
* ''postlink'' - Array of objects to link, added to the linker flags after linkflags. See below.
* ''sourcedeps'' - An array of output nodes which should be weak dependencies on each source compilation node.
* ''weaklinkdeps'' - Array of entries that will act as weak inputs to the linker. This is to ensure ordering; they do not affect the actual linker command.
* ''symbol_files'' - One of three values:
**<tt>'bundled'</tt> - If possible, debug information will be generated into the binary. On some compilers this is not possible. For example, MSVC always generates .PDB files.
**<tt>'separate'</tt> - Separates debug information into a separate file (a .pdb file, .sym file, or dSYM package depending on the platform).
* ''version'' - Returns an object representing the compiler version. It may be stringified with <tt>str()</tt>. It can also be compared to either integers, other version objects, or strings. For example: <tt>compiler.version >= '4.7.4'</tt> will return true if the compiler's version is at least <tt>4.7.3</tt>. The exact meaning of the version is vendor-dependent; for example, MSVC versions look like large numbers (<tt>1800</tt> corresponds to Visual Studio 2013).
* ''family'' - Returns the compiler family. This is either MSVC, GCC, Clang, or SunPro.
* ''behavior'' - Returns the compiler meta-family, or the most generic compiler this compiler tries to emulate. This is either MSVC, GCC, or SunPro.

Entries to <tt>linkflags</tt> and <tt>postlink</tt> can be:
* A string representing a linker flag.
* An <tt>Entry</tt> object.
* A <tt>Dep</tt> object. <tt>Dep</tt> objects are useful when precise control is needed over what text is given to the linker in order to link in a file. Essentially, they let you customize the link flag while still including a dependency. They also allow lazy computation of dependencies, since sometimes extra steps must be generated before linking to an object. <tt>Dep</tt> objects have two attributes:
** <tt>text</tt>, the text that will be passed to the linker when constructing its argument list.
** <tt>node</tt>, an object which tells AMBuild how to build a dependency for the linker flag. It can be:
*** <tt>None</tt>, meaning that the text is a file path.
*** A file path.
*** An <tt>Entry</tt> or list of <tt>Entry</tt> objects representing the output files of a command, or
*** A function which returns the above, and has the signature <tt>(builder, binary)</tt>, receiving a <tt>Context</tt> object and a <tt>BinaryBuilder</tt> object.
* ''Note:'' AMBuild does not currently support automatic dependency generation for <tt>-L</tt> style linking.

For example, to generate a linker invocation like "<tt>g++ main.o tier1.so -o main</tt>", where <tt>tier1.so</tt> is a generated file, you could do:
<Python>
binary.postlink += [binary.Dep('tier1.so', tier1_so_entry)]
</Python>

If this requires symlinking <tt>tier1.so</tt> to be in the local folder, you can get more complex, such as:
<Python>
def make_linker_dep(compiler, name, entry):
def lazy_dep(builder, binary):
cmd, (output,) = builder.AddSymlink(entry, '.')
return output
return compiler.Dep(name, lazy_dep)
</Python>

==Methods==
There are two APIs for creating C++ binaries - <tt>ProjectBuilder</tt> and <tt>BinaryBuilder</tt>. <tt>ProjectBuilder</tt> makes it possible to group related tasks together. For example, if one binary has multiple build configurations, a <tt>Builder</tt> will allow you to group them together with a common set of source files. For building, the results are exactly the same as creating individual <tt>BinaryBuilder</tt>s.

For generating IDE project files, the distinction can be important. When the same binary is built across multiple configurations, AMBuild generates a new project file for each configuration. Using <tt>ProjectBuilder</tt> over <tt>BinaryBuilder</tt> allows AMBuild to store each of the configurations in a single project file.

* <tt>Program(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>Library(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibrary(name)</tt> - Creates a new <tt>BinaryBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>ProgramProject(name)</tt> - Creates a new <tt>ProjectBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate an executable (<tt>.exe</tt> is automatically appended on Windows).
* <tt>LibraryProject(name)</tt> - Creates a new <tt>ProjectBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a shared library. <tt>.so</tt>, <tt>.dylib</tt>, or <tt>.dll</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>StaticLibraryProject(name)</tt> - Creates a new <tt>ProjectBuilder</tt> instance, with a copy of the compiler settings. The builder is configured to generate a static library. <tt>.a</tt> or <tt>.lib</tt> is automatically appended depending on the platform. Nothing is ever prepended to the name.
* <tt>Dep(text, node)</tt> - Creates a <tt>Dep</tt> object instance (see above for more details).
* <tt>like(name)</tt> - Returns whether the compiler is "like" another compiler. This is intended to represent the compatibility hierarchy of modern compilers. For example:
** Visual Studio is "like" 'msvc'.
** GCC is "like" 'gcc'.
** Clang is "like" 'gcc' and 'clang'.
** Note that GCC is not "like" Clang.
* <tt>pkg_config(pkg, link = 'dynamic')</tt> - Runs the pkg-config program for the given package name, and adds relevant includes, cflags, and libraries to the compiler. If <tt>link</tt> is 'dynamic' (default), shared libraries are used. If <tt>link</tt> is 'static', then static libraries are used instead.

=BinaryBuilder=
<tt>BinaryBuilder</tt> assists in creating C/C++ compilation tasks. Once you've set all the information needed, they are integrated into the dependency graph by using <tt>builder.Add()</tt>.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>BinaryBuilder</tt>. Modifying this compiler will not modify the original <tt>builder.cxx</tt>.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.
* ''type'' - One of 'static', 'library', or 'program'.
* ''custom'' - A list of custom steps to include in the compilation process. See [[#Custom C++ Tools]].

==Methods==
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.
* ''Module(builder, name)'' - Creates and returns a new ''Module'' object that is attached to the BinaryBuilder it was invoked on. The module object has two properties: ''compiler'', a clone of the current compiler on the BinaryBuilder, and ''sources'', and empty list. Source files added to the module will be compiled as part of the BinaryBuilder that created it, however, they will use the module's compiler settings instead. Modules may be added from any context, and are intended for large monolithic projects that have many components that must be linked together.

=ProjectBuilder=
<tt>ProjectBuilder</tt> assists in creating multiple configurations of a C++ compilation task. Set the source list via <tt>sources</tt>, then use <tt>Configure()</tt> to add a new configuration. After all configurations have been added, use <tt>builder.Add()</tt> to add the project to the dependency graph.

When calling <tt>builder.Add()</tt> on a project, the return value is a list of <tt>CppNode</tt>s, one for each configuration in the order they were added.

==Attributes==
* ''compiler'' - A full copy of the compiler settings used when instantiating this <tt>ProjectBuilder</tt>. Modifying this compiler will not modify the original <tt>builder.compiler</tt>.
* ''sources'' - An (initially empty) list of C/C++ source file paths. They can be absolute paths, or paths relative to <tt>currentSourcePath</tt>.
* ''localFolder'' - The name of the folder this binary will be generated in, relative to the <tt>buildFolder</tt> of the context that adds the tasks.

==Methods==
* ''Configure(name, tag)'' - Returns a <tt>BinaryBuilder</tt> with the given name. The tag is used to describe the configuration for IDE project files.
* ''Dep(text, node)'' - A wrapper for <tt>compiler.Dep</tt>.

=C++ Detection=
When using the <tt>DetectCxx</tt> API, AMBuild uses the following logic to find a C++ compiler:
<ol>
<li>If 'CC' and 'CXX' are defined in the environment, those most result
in a valid compiler, and no other detection is performed. On
Windows, tools like "rc" and "lib" must be in the environment.
Defining CC but not CXX (or vice-versa) is an error.</li>
<li>If running on Windows, if 'cl.exe' is in PATH, then AMBuild assumes
the environment has already been configured, and looks for, in this
order: cl, clang, gcc, icc.</li>
<li>If running on Windows, and 'cl.exe' is not in PATH, then AMBuild
looks in the registry for Visual Studio 2015. It will also look for
the 'vswhere' tool, and if present, will detect installations of
Visual Studio 2017 and 2019. The highest working version is used. If
no working version is found, the logic in step 2 is used as a
last-ditch attempt.</li>
<li>Otherwise, AMBuild tries to run clang, gcc, or icc (in that order).</li>
</ol>

Note that on Windows, this logic is heavily dependent on vcvars being functional. For example,
Visual Studio 2015 may not configure newer Windows Kits properly, and
AMBuild will not be able to automatically detect such an install. We recommend that for continuous integration, and reproducible, release-quality builds, that the environment be entirely configured beforehand (eg, the environment set up, and CC/CXX set properly).

==Options==
As of AMBuild 2.1.1, options may be specified in adictionary given to <tt>DetectCxx</tt>. Any unused options will be left in the dictionary after the call returns, and any consumed options will be removed.

Available options:
<ul>
<li><tt>force_msvc_version</tt> - A string specifying which version of MSVC can be used during automatic detection. This only applies to searches for MSVC installations, not for "cl.exe" in the environment or when CC/CXX has been manually set. The string should be a version number (eg, "14.0", "15.0", or "16.0" etc).
</ul>

Not that since the <tt>options</tt> argument is specific to AMBuild 2.1.1 and higher, projects wanting to maintain backwards compatibility can use this snippet to detect its availability:

<python>
apiVersion = getattr(builder, 'apiVerison', None)
if apiVersion and apiVersion >= '2.1.1':
cxx = builder.DetectCxx(cxx_options)
else:
cxx = builder.DetectCxx()
</python>

=Custom C++ Tools=
BinaryBuilders have a "custom tool" list that allows build scripts to hook into the compilation process. Usually, custom entries will be fully provided by an AMBuild helper or a third party helper. However it is possible to write your own custom tools.

FXC is a good example of when a custom tool is needed. FXC is a Microsoft tool for compiling HLSL shaders. It has a mode to generate C++ headers, but it's extremely cumbersome to work with, and AMBuild can hide that complexity while safely integrating it into the dependency graph.

Custom tools are objects added to the <tt>custom</tt> list on a <tt>BinaryBuilder</tt>. This object must have a <tt>tool</tt> attribute, containing an object with the following methods:
* ''evaluate(cmd)'' - Called when the BinaryBuilder is submitted to the build tool.

The ''cmd'' parameter to ''evaluate'' is an object with the following properties:
* <tt>context</tt> - The build context for the module that the tool will run against.
* <tt>localFolderNode</tt> - A folder node, representing the output folder for the module's object files.
* <tt>data</tt> - The custom object given to the BinaryBuilder, that this tool should process.
* <tt>compiler</tt> - The compiler object for the module this tool is running in.

Additionally, the ''cmd'' object has properties which are considered outputs:
* <tt>sources</tt> - An optional list of additional sources to compile. The tool may append new items.
* <tt>sourcedeps</tt> - An optional list of additional source dependencies. The module's <tt>sourcedeps</tt> array will be extended to include anything the tool adds here.

Finally, the ''cmd'' tool has helper methods:
* ''NameForObjectFile(path)'' - Computes a "safe" object file name for the given path. All characters that do not conform to C++ identifier name rules are replaced with an underscore.
* ''ComputeSourcePath(path)'' - Computes a command-line safe source path for an external tool. The output is either an absolute path, or a path relative to <tt>cmd.localFolderNode</tt>.
* ''CustomSource(source, weak_deps=[])'' - Returns an object that acts as a source file for a source file list. However, it can be annotated with extra instructions to the build process.
** <tt>weak_deps</tt> - An additional list of weak dependencies for this source file.

When the binary is submitted to the build, the custom tool will have the chance to include any extra steps it wants. It should execute these steps, if possible, in the same folder as <tt>cmd.localFolderNode</tt>. If these steps introduce new source files, they should be included in <tt>cmd.sources</tt>. New weak dependencies should be included in <tt>cmd.sourcedeps</tt>. If no dependencies at all are introduced, then you probably don't need a custom tool, as the C++ binary is not dependent on anything custom.

=Predefined Custom C++ Tools=

* See [[AMBuild FXC API]]

=Changes from 2.0=
If upgrading from the 2.0 API, the following changes should be noted:
* <tt>Context.DetectCompilers</tt> has been renamed to <tt>Context.DetectCxx</tt>.
* <tt>Context.compiler</tt> has been renamed to <tt>Context.cxx</tt>.
* <tt>Context.RunScript</tt> and <tt>RunBuildScripts</tt> have been renamed to <tt>Context.Build</tt>.
* Paths to <tt>RunBuildScript[s]</tt> may now be specified as relative to the root of the source tree, by prefixing the path with '/'.
* The <tt>vendor</tt> property on <tt>Compiler</tt> is now undefined. It must not be accessed or compared. Use the new <tt>family</tt> or <tt>behavior</tt> accessors, or use the <tt>like()</tt> method.
* The <tt>debuginfo</tt> property on <tt>Compiler</tt> has been renamed to <tt>symbol_files</tt>, and it no longer accepts <tt>None</tt>.
* The <tt>cc</tt>, <tt>cxx</tt>, and <tt>argv</tt> properties on <tt>Compiler</tt> have been removed.
* The <tt>target_platform</tt> and <tt>host_platform</tt> fields on Contexts have been replaced with the <tt>target</tt> and <tt>host</tt> System objects. It is enough to replace <tt>target_platform</tt> with <tt>target.platform</tt> and <tt>host_platform</tt> with <tt>host.platform</tt>.
* It is no longer possible to run a script from a context that is no longer the active context.

AMBuild API

2020-08-23T07:44:59Z

BAILOPAN: /* Options */