Difference between revisions of "AMBuild API (2.0)"

From AlliedModders Wiki
Jump to: navigation, search
m (remove AddDependency)
m
Line 1: Line 1:
 
AMBuild scripts have access to the following object types:
 
AMBuild scripts have access to the following object types:
 
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''configure context''.
 
* '''Context''': Exposed as the <tt>builder</tt>, this is the entry point for the API and is known as a ''configure context''.
* '''NodeBuilder''': Represents a node in the dependency graph that may or may not be committed to the database.
+
* '''Entry''': Represents a node in the dependency graph.
 
* '''Compiler''': An abstraction representing a C++ compiler environment.
 
* '''Compiler''': An abstraction representing a C++ compiler environment.
 
* '''Vendor''': An abstraction representing a C++ compiler vendor (GCC, MSVC, Clang, etc).
 
* '''Vendor''': An abstraction representing a C++ compiler vendor (GCC, MSVC, Clang, etc).
Line 28: Line 28:
 
* ''buildPath'' - The absolute path to the build folder.
 
* ''buildPath'' - The absolute path to the build folder.
 
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
 
* ''buildFolder'' - The working directory of jobs in this context, relative to <tt>buildPath</tt>.
 +
* ''localFolder'' - The <tt>Entry</tt> for creating <tt>buildFolder</tt>; <tt>None</tt> for the root of the build.
  
 
==Methods==
 
==Methods==
Line 42: Line 43:
 
** ''taskbuilder'' - The job builder instance.
 
** ''taskbuilder'' - The job builder instance.
 
** Returns a value based on the taskbuilder. For example, C++ objects return a 'CppNode' described under the Compiler section.
 
** Returns a value based on the taskbuilder. For example, C++ objects return a 'CppNode' described under the Compiler section.
* ''AddSource(source_path)'' - Adds a source file as an object in the dependency graph. Source objects can be dependencies for other objects, but they themselves should not have dependencies. If a source file with the same path already exists, it will be re-used.
 
** ''source_path'' - An absolute path to the source file; it can be anywhere in the filesystem, except that it must not be in the build folder. Anything in the build folder is considered an output.
 
** Returns a <tt>NodeBuilder</tt> instance describing the dependency graph node.
 
 
* ''AddFolder(folder)'' - Ensures that a folder is created when performing a build. The folder is created relative to the context's local build folder.
 
* ''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.
 
** ''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 a <tt>NodeBuilder</tt> instance describing the folder creation node.
+
** 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.
 
* ''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.
 
* ''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.
 
** ''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:
 
** ''output_path'' - One of the following:
*** A string path ending in a path separator, or <tt>'.'</tt>, or a string path containing a folder added via <tt>AddFolder()</tt>, representing 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 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 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.
 
*** 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 a <tt>NodeBuilder</tt> instance representing the node for this command in the dependency graph.
+
** See <tt>AddCommand</tt> for return values.
 
* ''AddCommand(argv, 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>.
 
* ''AddCommand(argv, 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>.
 
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
 
** ''argv'' - The argument vector that will be passed to <tt>subprocess.Popen</tt>. <tt>argv[0]</tt> should be the executable.
 +
** ''inputs'' - An iterable containing source file paths and/or <tt>Entry</tt> output-file nodes that are incoming dependencies.
 +
** ''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>.
 
** ''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.
 
** ''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.
 
** Returns a 2-tuple, containing:
 
** Returns a 2-tuple, containing:
*** A <tt>NodeBuilder</tt> instance representing the node for this command in the dependency graph.
+
*** An <tt>Entry</tt> instance representing the node for this command in the dependency graph.
*** A list of <tt>NodeBuilder</tt> instances, each instance corresponding to one of the output file paths specified.
+
*** A list of <tt>Entry</tt> instances, each instance corresponding to one of the output file paths specified.

Revision as of 20:54, 11 November 2013

AMBuild scripts have access to the following object types:

  • Context: Exposed as the builder, 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.
  • Vendor: An abstraction representing a C++ compiler vendor (GCC, MSVC, Clang, etc).
  • BinaryBuilder: An abstraction 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.
  • 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.

Contexts

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

When using paths inside a context, it is important to note how AMBuild recognizes paths.

  • source paths are any paths that are absolute. They must not resolve to a path inside the build folder. Source paths are considered inputs to the build.
  • output paths are any paths that are relative. They are always relative to the build folder. Output paths are generated by the build process.

Attributes

  • compiler - An instance of a Compiler object, or None if DetectCompilers was never called. Calling DetectCompilers will set the compiler field for this and all future contexts.
  • parent - The context that loaded the current context.
  • script - The path, relative to sourcePath, of the current build script.
  • sourcePath - The absolute path to the source tree.
  • options - The result of evaluating command-line options from configure.py, via the optparse module.
  • buildPath - The absolute path to the build folder.
  • buildFolder - The working directory of jobs in this context, relative to buildPath.
  • localFolder - The Entry for creating buildFolder; None for the root of the build.

Methods

  • SetBuildFolder(folder) - Sets the working directory of jobs in this context, relative to buildPath.
    • folder - A string representing the folder path. '.' and './' are allowed.
    • Returns None.
  • DetectCompilers() - Detects C and C++ compilers and raises an exception if neither are available or they do not match. Should only be called once.
    • Returns a Compiler object that is also accessible via the compiler attribute.
  • RunBuildScripts(files, vars={}) - Runs additional build scripts.
    • files - An iterable containing a list of file paths relative to path of the current build script, or a string containing such a path.
    • vars - An optional dictionary of global variables to set in each child build script. The dictionary is merged with the global variables passed into our current script. Variables with the same name are overridden by the new dictionary.
    • Returns None.
  • 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, C++ objects return a 'CppNode' described under the Compiler section.
  • 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 Entry 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 '.', 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 AddFolder(), 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 AddCommand for return values.
  • AddCommand(argv, 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 AddDependency.
    • argv - The argument vector that will be passed to subprocess.Popen. argv[0] should be the executable.
    • inputs - An iterable containing source file paths and/or Entry output-file nodes that are incoming dependencies.
    • folder - The working directory for the command. By default, this is buildFolder. It can be None to specify the root of the build. Otherwise, it must be an Entry from calling AddFolder or reading localFolder.
    • 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.
    • Returns a 2-tuple, containing:
      • An Entry instance representing the node for this command in the dependency graph.
      • A list of Entry instances, each instance corresponding to one of the output file paths specified.