aimake - build and/or install C programs with minimal configuration
The most common way to build and install a program using aimake is:
mkdir build; cd build; ../aimake -i installdir
or to install for all users, rather than just yourself:
mkdir build; cd build; ../aimake -i /usr/local -S sudo
Commonly used options:
Produce more verbose output (can be given multiple times).
Install the program into the specified directory, as well as building it.
When installing, use the specified program (normally su or sudo) to gain administrator permissions.
Turn on the specified feature of the program you are building.
For full documentation on aimake, use the --documentation argument.
aimake is a build system for C programs that attempts to deduce as much as possible itself,
rather than requiring a separate file along the lines of Makefile,
config.ac,
or CMakeLists.txt.
In the most common cases,
no configuration file is required at all,
although a rudimentary configuration file can be used to specify more complicated things that cannot be automatically deduced (such as which files contain the entry points to libraries,
or what commands to use to generate generated source files).
To compile a project with aimake for the first time, create an empty directory, then call aimake from that directory. By default, it will compile the source files in the same directory tree as aimake itself. You can use a version of aimake other than the version shipped with the project by running your version of aimake (from the build directory), and giving the path to the root of the project's distribution as an argument. To rebuild the project, call aimake with no arguments in your build directory. To install it, call aimake with the -i switch, and specify where you want to install it (you can use just -i by itself to install in the same place as last time).
Set how verbose the build should be. The default level is 0; higher values produce more verbose output. (You can get higher values via specifying a number, or via specifying the -v option multiple times.) The messages you get at each verbosity level are:
No messages at all. Even important ones.
Messages about warnings, errors, and failures to compile. No messages will be printed if everything works correctly.
Level -1 messages, plus messages about operations that aimake is performing that actually contribute to compiling the code (e.g. running compilers, linkers, and so on). At level 0 and above, aimake also displays the details of what it is thinking temporarily, using one line that repeatedly changes.
Level 0 messages, plus messages about other operations that aimake performs (such as determining dependencies).
Level 1 messages, plus a record of all the actual commands that are run. Additionally, the temporary messages about what aimake is doing are left on the screen, rather than removed.
Level 2 messages, plus descriptions of which rules aimake is considering to run and why. This is mostly useful for debugging aimake, but may also help to debug performance issues with rules.
Level 3 messages, plus information useful mostly for debugging aimake itself.
Level 4 messages, plus particularly verbose information useful mostly for debugging aimake itself.
Specifies the install directory for the project being built. If this option is not given, aimake will use the same directory as last time, or a default directory on the first build. It is also possible to give -i with no directory; this is equivalent to explicitly specifying the same directory as last time.
If the directory in question does not exist, it must be given with an absolute path. (Relative paths are OK if the directory already exists.)
The specific directories to install in are deduced from the directory given. For instance, if on a UNIX/Linux system you gave /usr/local as the directory to install into, aimake would put the application's read-write data files under /var/local, whereas installing into /usr would put them under /var/lib, and installing into /home/user/package would put them inside the install directory. You can control the details of the install with the --directory-layout option or "directory_layout" configuration option.
This option, together with -S, control whether aimake will attempt to install the project, or just build it:
Specifies an appropriate command to use to elevate permissions (on UNIX-like systems, normally su, sudo or gksu, but depending on what you're trying to do you might want to use fakeroot or even sudo checkinstall). If this option is not given, aimake will not be able to install into a location that isn't writable by normal users. (You should not run aimake directly as root; doing that means that the files in the build directory are written as root, which normally causes problems.)
The "traditional" method of installing a program for an entire system is to use the -i and -S options to get aimake to do the installation itself. However, this has a few drawbacks: it doesn't integrate with your computer's package management framework, there's no easy/obvious way to uninstall, and you can't easily transfer the binaries to another system.
An alternative method is to generate an installer package, which can then be installed on your computer, or (if the architectures and operating systems are sufficiently similar) on someone else's computer. That's performed using the --gen-installer option. This option will set most other options accordingly for the platform, and so the other options typically won't be needed. One that might be is --with/--without; if you disable a feature, it won't be built and the installer won't install it, but if you enable a feature, some installers will still be able to give the option to not install the feature (even though it has been built).
Generating an installer needs more dependencies than merely building. Here are the various installer formats, and the dependencies they need:
Generates a Windows Installer package, for use on Microsoft Windows. (This should theoretically work on Windows 2000 SP3 and up, but full functionality will not be available in versions before Vista, and this has only been tested on Windows 8.1.) This requires you to install WiX, an installer generator toolkit for Windows (and to place its binaries on your PATH).
This option is implemented via setting -i, --directory-layout, --destdir, and --filelist, then feeding the resulting file list to WiX (together with appropriate command-line options).
The architecture of the generated package will match that of the system you're building on: 64-bit if you build on a 64-bit system, 32-bit if you build on a 32-bit system. (Perhaps some day, there'll be an option to cross-compile.)
It is highly unlikely that this option will work unless you're running on a Windows system yourself.
The --var option makes it possible to easily override some commonly overriden options. If this option is not given, the default is taken from the environment variable of the same name, (failing that) defaults specified by the project you are compiling, and (failing that) a default value provided by aimake:
The C compiler toolchain to use (normally gcc or clang).
This must be the name of a command that exists on your system,
and compiles C with the -c option,
preprocesses it with the -E option,
etc..
The default is gcc.
Like CC, but for C++. The default is g++.
Overrides the C and C++ preprocessor to use. The default is whatever program is indicated by CC, with the -E option.
Command-line arguments to use when building C programs. The default is -g -O2 -Wall. (aimake will also add a few extra options of its own, depending on your platform, in order to ensure that the build works correctly.)
Command-line arguments to use when building C++ programs. The default is -g -O2 -Wall.
Command-line arguments to use when preprocessing C or C++. The default is to give no options besides those required for aimake to function correctly.
Command-line arguments to use when linking. The default is to use no special options. (Note that you don't need to, and shouldn't, include the -l options that specify dependencies on libraries; aimake should figure those out by itself.)
Command-line arguments to pass to yacc.
The default is to pass no options beyond the --defines= that aimake always provides because it needs special handling (to place the files in the right place).
Command-line arguments to pass to lex.
The default is an empty set of options.
Note that this option is not "sticky"; the value has to be given anew with every compilation, or it will revert to its default. (In particular, it's not useful to give it alongside --config-only.)
Leading and trailing spaces in the option to --var (or an environment variable) will be removed,
and consecutive spaces will be collapsed to one space,
because such extra whitespace is not typically intended to add the null string as an option.
aimake currently does not perform any other sort of shell unescaping on the values of these variables.
Instead of compiling, output all error and warning messages that were obtained during the last compile, for files matching the given regexp. (Don't include the // around the regexp.)
This option is currently unimplemented.
Attempt to regenerate the given object and rebuild everything that directly depends on it, even if aimake has no reason to think that anything would be different this time. (This will typically also cause things that indirectly depend on the given object to be rebuilt.) This option can be given multiple times.
Change how the specific install directories are chosen. The possible values with the default configuration are:
Install into the appropriate system directories that are intended to be managed by the package manager on a UNIX/Linux system; the install directory should be /usr or /. This is automatically chosen as the layout when installing into /usr or /. This option would mostly be used by package managers; --destdir would also be used for package managers that operated using binary packages (as oppose to directly from source). ("FHS" stands for "File Hierarchy Standard", the standard that specifies which files should be placed in which directories on a UNIX or Linux system.)
Install into the appropriate system directories on a UNIX/Linux system, avoiding directories that are normally maintained by package managers. This is automatically chosen as the layout when installing into /usr/local, the only reasonable choice for directory, and so there should rarely be a need to specify it explicitly. (Most build systems have /usr/local as the default install directory on UNIX/Linux; however, aimake will not install into system directories unless the user explicitly requests it to.)
Install into system directories specific to the package being installed; every file will be placed into the install directory (by default, /opt/packagename), into /etc/opt/packagename, or into /var/opt/packagename. This install layout is often used to make it easy to install and uninstall packages by hand.
Place all the installed files in appropriate subdirectories of the given directory. This works on any operating system but Windows, and is the default when the install directory given is unrecognised, or recognised as a user's home or documents directory. (Note that this sort of install makes the program available only to one user, rather than system-wide.)
This is basically the same as single_user, except that it will place libraries into the same directories as executables, which is required for Windows to be able to find them.
Place all the installed files under CSIDL_PROGRAM_FILES (typically C:\Program Files\packagename, for read-only files) or CSIDL_COMMON_APPDATA (for read-write files) as appropriate, as is standard for system-wide installs on Windows. This option does not work on other operating sysems, which lack the appropriate system calls for locating these known folders.
Attempt to emulate the directory layout behaviour of autoconf and similar build systems.
Place everything into the same directory, no subdirectories involved (unless the configuration for the specific project requests that empty subdirectories are created). This is also special-cased to cause the program being installed to look for its data in the current directory, rather than memorizing the path it was installed to, even if it instructs aimake to tell it the install path.
Change the directory for a specific value of the install_dir option of an install action.
For instance,
--override-directory bindir=/bin would install binaries into /bin even if the default was,
say,
/usr/bin (which is the default with -i /usr).
See the documentation for install_dir for a full list of directories you can override.
On Windows, if the overriden directory is inside a known folder such as Program Files, then it will be interpreted relative to that known folder (i.e. if the known folder moves, the overriden directory will move to match).
When installing, treat the given directory as the root directory, rather than using the actual root directory. (For instance, giving -i /usr --destdir /home/user would install into /home/user/usr, but the installed program would look for paths as if it had been installed into /usr.) This is intended for use in packaging programs, and when installing into a chroot from outside the chroot. This option may only be given if the install directory is outside the source directory and outside the build directory (otherwise, it's not quite clear what it would mean).
Do not attempt to change or set the permissions of any file. By default, aimake will try to change permissions if installing with administrator rights.
This option generates a list of files being installed in the specified format, designed for use as input to an installer program. If --destdir is set, the file list will be placed in the root of that directory. Otherwise, it will be placed in the root of the build directory.
Generates a list of filenames and directory names of the installed files and directories. This is as seen by the installed program (i.e. the --destdir will be omitted). The filename will be filelist.txt.
Like basic,
but precedes each filename with its permissions,
in a form similar to that used by ls -l on a UNIX system.
Generates suitable input for WiX,
an installer generator for Windows.
The list will be placed in the directory given as an argument to --destdir,
with basename equal to the packagename option and extension .wxs.
aimake will try to map its own concepts onto WiX concepts as far as possible,
e.g.
aimake features will be controllable from the WiX UI,
and have the same default state (although obviously,
features will not be available in WiX unless they were turned on explicitly or implicitly in aimake,
because they won't have been built).
Some programs installed by aimake may have multiple configurations (e.g. they may be able to build both a command-line program and a GUI program); this option lets you select which features you want (--with) and/or don't want (--without). These options are "sticky"; they are saved in aimake.objects, and so persist into future runs of aimake in the same directory. If you want to remove the persistence of such an option, causing it to fall back to and respect changes to its default value, use --with-default.
The list of features that are supported by this option varies depending on which program you are installing.
You can use --with=? for a list (you might need to escape the ? to hide it from your shell).
Show the full documentation for aimake.
Show the license/copyright information for aimake.
Don't assume that whatever is connected to stdout supports any control codes but newline (not even carriage return). (This is mostly only useful if stdout is not a terminal).
aimake normally refuses to build into a directory that has not previously been used for an aimake build and that contains files,
to prevent catastrophic errors like overwriting your source directory with your build directory.
Sometimes,
you want to do something like redirecting the output from aimake,
or using debug or profiling tools that produce output before aimake starts running; in these cases,
you can specify --nonempty-directory to suppress the sanity check.
Before using this option,
make absolutely sure you are running from the correct directory.
This option can also be used to permit installing to the source or build directory, a combination that is typically disallowed because it makes no sense and can lead to accidentally overwriting the source.
Disables checks on permissions that are normally used to prevent yourself accidentally creating a file that can't be deleted. The most common reason to use this is if you're building as root because you're using a system or jail that has no regular users.
Don't run any rules but install rules,
even if they're marked using sys:always_rebuild.
This is used by aimake internally when it elevates permissions.
Note that if the build is not fully up to date,
this may lead to only a partial install.
Pretty much the only reason to use this manually is immediately after running aimake with no -i option, perhaps with elevated permissions, in cases where you have a reason to separate the build and install steps.
Instead of compiling, dump the internal statefile to stdout in a human-readable format. This is mostly only useful for debugging aimake.
It is possible to specify a subset of the statefile to dump as a comma-separated sequence of keys (e.g. 'xuse_by_object,config_option:libdir'). On large projects, this is considerably faster than dumping the entire statefile if you are only interested in a small portion of it.
After building, output statistics on how much time was spent on each rule. Does not work in combination with -S (because elevating permissions requires exiting and restarting the aimake process, and the profiling data is lost upon exit).
Causes aimake to do nothing but record persistent options in the statefile. This lets you incorporate aimake into build systems that expect a "configure, make, sudo make install" workflow, e.g.:
../aimake --config-only -i /usr/local
../aimake
sudo ../aimake --install-only -i
Note that the use of --install-only allows aimake to be run successfully as root; normally it refuses to be run with root permissions.
In addition to the built-in configuration (unless --ignore-builtin-config is used), aimake.rules, and aimake.local, also read configuration from the given file. This option can be given any number of times.
Ignore all the built-in rules and options, reading configuration only from the project-specific configuration file and --local-config options. aimake has only minimal functionality with no rules (for instance, it will not even check for changes to files in the source directory), and as such, this is mostly only useful for testing aimake, or if you want to use aimake's engine for something radically different from compiling C and have a complex configuration file handy for that alternative use. (The built-in directory layouts are not ignored, but they will not be used for anything if directory_layout is set to something other than a built-in directory layout.)
Normally, if something goes wrong compiling your code, aimake exits with exit code 1. aimake checks for certain specific common mistakes (such as forgetting to anchor a regular expression in a dependency rule, or using the wrong inclusion syntax); with this option, each of those mistakes will produce a specific exit status (not 0 or 1). The main purpose of this is for use in aimake's testsuite, to test that those errors are being detected correctly.
Show aimake's version number (and a summary of the license).
Show a short usage message for aimake (that omits most of the options).
Build systems like make work via an explicitly given directed graph of dependencies. The user specifies which files they want to rebuild (although most Makefiles specify a default, this still needs to be given explicitly), then make recurses depth-first through the dependencies, rebuilding each file that is older than any of its dependencies.
There are several problems with this approach. The main problem is that it costs a lot of programmer time; whenever any changes are made to the dependency graph (most commonly due to adding a new source file or new target), the programmer must alter the Makefile to specify the new relationships between files. This problem was enough to motivate the creation of aimake by itself. Dependency tracking is something that can be done by a computer almost as easily (and much more quickly) than a human can, given the existence of dependency-determining programs such as cpp -M (for C header files) or nm (for object files and libraries).
There are some other, more minor, problems:
aimake_get_option("installdir"). Likewise, aimake will define a preprocessor symbol like AIMAKE_BUILDOS_linux, so that you always know which platform you're running on.Many other build tools are available that try to fix one or more of these problems, but as far as I know, aimake is the only program which tries to fix them all at once.
aimake is designed to be as easy as possible to use with new projects, and as such it often works with unmodified source and no project-specific configuration file. However, there are some steps you can take to get the best possible result.
First, make sure that the directory layout of your source tree reflects the dependencies between files; this helps to resolve ambiguities. It mostly doesn't matter if all your symbols have different names, but if you declare the same function or variable in multiple files, aimake will need to know which to link against. It will favour linking against files that it has to link to anyway, but when all else fails, it will fall back to linking to files in the same directory (and with as many matching characters as possible at the start of the filename, as a second tiebreak). Also make sure that files have appropriate extensions (.c for C files, .cxx for C++ files, .h for headers, etc.).
Next, you can use some aimake-specific macros in your C and C++ source and header files. One reason to do this would be if you have code specific to one operating system; you can use AIMAKE_BUILDOS_ macros to conditionalize your code to one operating system, for instance AIMAKE_BUILDOS_linux, AIMAKE_BUILDOS_MSWin32, or AIMAKE_BUILDOS_darwin (typically indicating Mac OS X). (The possibilities for the build OS are generally taken from Perl's $^O operating system identification variable, but msys is folded into MSWin32 in order to correctly indicate the operating system on which the resulting programs will run.) Another is to make your code depend on aimake configuration options; aimake will provide a function aimake_get_option that lets you get the value of an option at runtime (allowing for OS conventions, such as roaming profiles on Windows, which may change filesystem location while remaining the same directory).
Although aimake will identify which executables it should produce as output (via looking for functions called main), it will not produce shared libraries without an indication of which symbols form the API of the shared library. In order to create shared libraries correctly on all operating systems, aimake will need to know which symbols are imported from shared libraries (that you create; the system header files will contain this information for system libraries), and which symbols are exported from shared libraries, via wrapping their names in macros, e.g.:
int AIMAKE_EXPORT(library_function)(void); /* exported function */
int AIMAKE_IMPORT(library_function)(void); /* imported function */
The names only need to be wrapped this way in the declaration, not the definition (which can be left unchanged). AIMAKE_IMPORT and AIMAKE_EXPORT only work correctly when the type of a variable, or return type of a function, is a single identifier (not some complex chain of arrays and pointers, etc.), so for complicated return types you will need to use a typedef:
char *function_returning_a_string(void) /* not imported or exported */
typedef char *char_p;
char_p AIMAKE_EXPORT(function_returning_a_string)(void) /* exported */
(The AIMAKE_IMPORT/AIMAKE_EXPORT API is potentially subject to change, in case I find a notation that avoids this problem.)
In addition to AIMAKE_IMPORT and AIMAKE_EXPORT, there are also AIMAKE_REVERSE_IMPORT and AIMAKE_REVERSE_EXPORT, which mark symbols that exist in the file using the library, and are used by the library (rather than the other way round, a much more common scenario). Note that some platforms may have restrictions on the dependency graphs of libraries; the currently known restrictions are as follows:
If aimake sees any symbols tagged as AIMAKE_EXPORT, it will place them in a shared library (and, if appropriate, link executables it creates against that shared library). The name of the library will be based on the common prefix of the source files that export symbols in the library (so, e.g., if they have wildly varying filenames but are all in the same directory, it will be named after the directory). As an exception, directories called src are ignored for naming purposes, because that name is very commonly used when source files and include files are separated into different directories.
Shared libraries often have an OS-specific versioning system. When exporting symbols, you can specify a version number for the shared library they create, as follows:
AIMAKE_ABI_VERSION(1.2.3)
The first component of the version number should be increased whenever a change is made to the library's ABI or API that would invalidate existing programs that used that library. The other components of the version number are arbitrary (and need not exist).
Finally, you can request that a file not be compiled in certain configurations via making it conditionally error out:
#ifdef AIMAKE_BUILDOS_MSWin32
# error !AIMAKE_FAIL_SILENTLY! This file should not be built on Windows.
#endif
The #error !AIMAKE_FAIL_SILENTLY! will cause the compilation to error out silently, without the user being informed of an error in the file. (Note that this can happen while aimake is locating header files necessary to be able to use the file; as such, you should ensure that the error happens based only on the individual file being compiled, and does not depend on anything that might be included from a header file.)
Different platforms have different conventions for documentation; on Linux, for instance, you would want your programs to be added to the manual called by man, and on Windows, it's more common to have separate HTML files. aimake's documentation system is inspired by Linux's, but uses a friendlier source format (Plain Old Documentation) rather than forcing you to write plain *roff, and will convert the manual pages to an appropriate format on systems which do not have manual page readers installed by default. You can just save the .pod file anywhere in your source tree, and aimake will handle it appropriately (in terms of install location, etc.).
See perlpod for information about the Plain Old Documentation format. For use in aimake, you need to add two extra lines to your POD file (failing to add these is an error):
Specifies the purpose of this manual page. The sections are as follows:
3pm, and TCL functions in 3tcl. Usual practice is to have one manual page for each group of closely related functions; in languages with packages or namespaces, documenting one package or namespace per page would make sense, but you will need to come up with your own division for less disciplined languages like C.Specifies the name of the manual page. In sections 1, 6, and 8, this is the name of the program that the manual page is associated with. In other sections, choose a suitable name that describes the situation. Except when other considerations exist (e.g. when documenting a function containing uppercase letters in a case-sensitive language), favour short names (one or two words at most), lowercase letters, and (if you have to use multiple words) separating words with underscores.
A special case of documentation is the license agreement. This can be marked using =for aimake eula (and should not have the manualsection and manualname lines); there should only be one. Not all installers will care about this; currently, it is only used on Windows when creating a WiX installer, which will show it to the user before installation (requiring the user to accept it), and also install it as "license.rtf" in docdir.
In addition to changing the source and headers that make up your project, it is also possible to add a project-specific configuration file, that contains configuration options or rules overrides. This should be a file named aimake.rules in the source directory. (A second file, named aimake.local, can also be used; the idea is that aimake.rules can be kept under version control and provided by the project authors, with aimake.local used for local changes. You can also use --local-config to add further configuration files.) Here's a sample configuration:
{
options => {
packagename => 'example',
packageversion => '1.0.0',
CFLAGS => '-Wall -Wextra -g -O2',
AM_CFLAGS => '-DBUILT_WITH_AIMAKE',
},
libraries => {
'z' => 'compress',
},
features => {
gui => {
description => 'Build a graphical user interface',
object => qr/^path:gui\/.*/,
default => 1,
},
},
}
The format of the configuration file is explained in much more detail later (see the section on configuration), in case you need to do something complex or custom. However, the most common tasks will be explained here:
There are some options that aimake is unable to automatically infer: the most important are the packagename and packageversion options, that tell aimake what name and version number that your project has. (Automated installation systems will need this information in order to be able to install your project correctly.) These are set using the options dictionary of the configuration file, using the syntax shown above. Note that because the packagename may be used for filenames, it has a very limited character set; you can use a separate packagename_text option if you want to use uppercase letters, punctuation, or the like.
For more information on the package-wide options you can set, see "THE options DICTIONARY".
The compiler flags (such as CFLAGS, flags to pass to the C compiler) can be set by the user using environment variables or the --var option (see the documentation for that option for the flags that exist). The defaults for these values can be set in the options dictionary, just as with package-wide options.
In addition to the regular CFLAGS and friends, there are also versions with an AM_ prefix (AM_CFLAGS, etc.). These will be combined with a possible user setting for CFLAGS. Thus, flags like -O2 that should be under user control should be placed in the CFLAGS; additional flags required for the correct functionality of your package should typically be in AM_CFLAGS.
The libraries dictionary allows you to link in additional libraries to your project. For each library, you specify the portion of the name of the library that the linker uses to find it (e.g. for the compression library "zlib", you specify z, because you link in the library using -lz), and you specify one symbol within that library (typically a function name, although you could also use an exported variable). In this case, we used compress; it's best to specify either a function that's part of the core functionality of the library and unlikely to change, or an initialization function that's required to use the library. (The specified symbol is used by aimake in order to ensure that the library is linked correctly.)
aimake will not report an error upon failure to find a library, unless it turns out that the library is actually required by the project. Thus, it's safe to specify a library that is only used in certain configurations, on certain operating systems, or the like; there won't be an error about a failure to find it in configurations where it's unused.
Many projects will want to provide multiple configurations, in which the user can choose what subset of the project to build. In aimake, this is accomplished via the features dictionary. The simplest version of this specifies a set of source files that will not be built if the feature is turned off, as is shown in the example configuration file. (You specify the files using a regular expression that matches filenames in aimake syntax, so that the same set of files is matched on every platform.)
For more information about defining features, see "THE features DICTIONARY".
aimake operates almost entirely using a set of rules (which are described in its configuration file; a default configuration file exists at the end of the aimake script, and can be augmented for a specific project via a file aimake.rules, if that project needs to do something unusual like generating some of its source files). Almost the entire build process is written in terms of rules; for instance, there is a rule to determine which files need compiling. (The main activities that occur without being driven by rules is to change the "hash" of sys:always_rebuild, to parse the configuration file into a set of objects, to verify that the build directory has not been tampered with (or recover if it has), and to handle side-effects of the install process; that's about it.)
Each rule has three parts. First are the conditions under which the rule runs; in order for a rule to run, all its dependencies must be in place, and the rule will be rerun if any of its dependencies change. A rule can have a hardcoded dependency list (in which case it only runs once in each compilation); alternatively, it can be parameterized by the object it applies to (its object field), in which case it runs once for each appropriate object, and its dependencies are also parameterize by the object. A rule that is parameterized by an object uses a regular expression to specify which objects it applies to, and it will run once for each appropriate object; the combination of the rule and object is known as a "pair" internally, and almost all internal operations are based on pairs rather than rules (rules with hardcoded dependencies and no objects are considered pairs of their own). So for instance, compile_c is a built-in rule; compile_c path:hello.c is a pair, that refers to the operation of running a compiler on hello.c, to create a file such as hello.o or hello.obj depending on platform. A rule's dependencies are specified in its command field.
The objects that make up a pair's dependencies can have dependencies of their own: a use dependency of an object is another object that will be included in any dependency list that contains the original object. A pair cannot run unless its command, its use dependencies, their use dependencies, and so on recursively, are all in place already (i.e. they exist, and none of the objects they were generated from have changed). A pair's object is also usually a dependency of the pair; aimake will include it in the pair's command by default, because it is usually appropriate, but this can be disabled manually using the object_dependency field of the rule (e.g. in cases where the pair's operation depends only on the object's name, and thus changes to the object). As an exception, if the pair's purpose is at least partially to determine dependencies of its object, then clearly it cannot depend on its object's dependencies (because it would lead to an infinite regress), so in this case, the pair depends only on the existence of the object itself, not on any of the object's dependencies.
The second part of the rule is the actual command that aimake runs in order to run the pair. This can be internal to aimake, part of the system's toolchain, or even an executable that was generated as part of the build process. This is calculated from the pair's dependencies; any cmd: or intcmd: object among the pair's recursively expanded use dependencies specifies the command to run (or if none are available, any bpath: object that refers to an executable, and failing that, intcmd:nop), and any optpath: and optstring: objects specify the command line options to that command. The rule's command thus specifies not only the pair's dependencies, but also the command to run to execute the pair, together with arguments to it; alternatively, the command or arguments can come from dependencies of objects in the command. Thus, it is quite common for a file to depend on whatever command-line option is needed to use that file in the commands that need to use it; a library libm could depend on optstring: -lm, for instance (although the details will vary by platform). This approach is slightly inflexible, in that it assumes that if a file is used as an argument to more than one command, each such command will expect the same syntax for specifying the file in question; although this is rarely an issue, the problem does come up occasionally, and although a workaround exists (via manipulating dependencies: objects manually and using the avoid_rules field of a rule), it is complex and error-prone. We intend to add a more direct way to accomplish this in the future.
The remaining part of a rule specifies what the rule accomplishes when it runs. There are several possibilities, and a rule can accomplish many of them simultaneously, or the same possibility applying to multiple different objects:
A pair can produce one or more files on the filesystem (and the matching object in aimake's internal state, which refers to that file). Typically, the file will have been generated by the command that was just run, but it is also possible to "produce" a pre-existing file in order to make aimake aware of it (in which case the information_only field of the rule should be set, or else aimake may well complain that your rule overwrote a file that it shouldn't be overwriting).
A rule can specify the files that it is producing in three ways. Often, the command that was run will take a command-line argument that specifies where to place its output; in this case, you can use output_from_optpath to tell aimake about this convention, and it will look in the same place for the output. Sometimes, the command that was run will print information about where it placed its output on standard output (in which case output can be a regular expression to match it), or standard error (in which case, you do the same and set also_match_stderr); this technique is particularly useful if you don't know what files will be output in advance. Finally, you can just hardcode a filename by using a constant value for output (that's a path:, bpath:, spath:, or standardlib: object).
Examples of built-in rules that produce files are compile_c that produces object files from C files, and generate_search_test_file which generates a specific file, bpath:aimake/aimake_1.c (and does not have a specific input object).
aimake objects are more general than just files on the filesystem; they can also refer to abstract concepts such as "functions named yyinput", "files with basename project.h", "options that are typically given to the C compiler", or the like. Pretty much the only difference between these and files on the filesystem, from the point of view of aimake's internals, is that they are defined entirely by their use dependencies, rather than having a file on the filesystem to match. When a pair provides an object, it specifies the set of objects it's producing, and a set of use dependencies for them; both the set of objects and the set of use dependencies are constructed out of components, any of which can be hardcoded, or obtained from the output of the command from a regex match; inner defaults to the pair's object. The produced objects are specified via output, outputarg, inner (output is concatenated to outputarg, and inner is added on the end if the object name is incomplete; likewise, outdepends is concatenated to dependsarg, with inner added on the end if the object name is incomplete).
The normal purpose of this sort of rule output is to determine under what circumstances a file can fulfil a dependency. For instance, the built-in rule o_file_provisions runs nm on an object file to obtain a list of the symbols in it, and provides appropriate symbol:, direct_symbol:, and symbol_in_object: objects to represent the symbols in question.
An object sometimes has use dependencies specified as it is created via the use of outdepends; this is useful when the same command that generates the objects also outputs the dependencies. Frequently, though, the command that determine the dependencies of a file (e.g. nm for an object file) will be different from the command that produces that file (e.g. cc for an object file), and objects can meaningfully have use dependencies even if they weren't even produced by aimake. Thus, there needs to be an approach to determine use dependencies of an object after it is created.
This can actually be accomplished without any extra types of rule behaviour: for each rule that wants to specify dependencies for an object, and each rule that can create that object, the first rule provides an object named dependencies:rulename:objectname, and the second rule adds that object as a use dependency of the original object while providing or producing it (via outdepends). Then all that is necessary is to set the object_dependency field of the rule that specifies dependencies to 'none'. However, this process is complex, and most importantly, requires all the rules that can provide an object to be modified every time a rule that wants to specify dependencies of that object is added.
using the actual root directory. (For instance, giving -i /usr As such, aimake provides sugar for this very common situation; using depends allows the rule to specify use dependencies of its object, using the mechanism explained above. This works identically to outdepends, building the dependencies piecewise out of depends, dependsarg (if present), and inner (if necessary).
An example of a built-in rule that adds dependencies to an object is ch_file_dependencies, which runs the preprocessor in order to determine the dependencies of a C source file, and (among other things) parses the output in order to determine which header files it attempted to include, adding file: dependencies as necessary.
Installing cannot be carried out in exactly the same way as other aimake operations, nor can it be carried out the same time, because it may need to run in a separate aimake process (for permissions-related reasons). Thus, a rule that installs a file cannot do anything else. Install rules have a install_dir field that specifies the directory in which their object should be installed; their command should not have side effects (although aimake cannot check this), and is typically omitted (although occasionally, a program will do a conditional install via giving one or more objects that need to have been built, along with intcmd:nop).
At the start of the build, aimake "changes" sys:always_rebuild, and parses the configuration file into config_option: and config_rule: objects. (The rules are in the configuration file, so it needs to be parsed separately.) It statically considers all optstring:, optpath:, intcmd: and cmd: objects to exist (as well as most sys: objects). Other objects are not statically considered to exist; in particular, path: and spath: objects need to be located via rule (there are built-in rules for this), or aimake will consider them nonexistent despite actually existing on the filesystem. This means that aimake will notice changes, additions, and deletions of files in the source tree (the files are "produced" via the built-in rule find_source_files; although this is run every time you run aimake, this does not cause the entire project to be rebuilt because most of the files will likely retain the same modification time or hash as last time).
From then on, everything is done by rules. Each pair is either changed, meaning that running it might potentially do something, or unchanged, meaning that nothing relevant has changed since last time it ran; initially, all rules are unchanged, but many will be marked as changed at the start of the run due to the "change" to sys:always_rebuild. (There's actually one more state internally, for optimization purposes: blocked pairs are changed pairs that are missing one or more direct dependencies. While a pair is blocked, aimake doesn't bother calculating its indirect dependencies, like it would with a non-blocked changed pair.) Each object (including nonexistent objects!) is either sure, meaning that aimake knows the object does not need to be rebuilt (either because it knows it's correct on disk / in memory, or because it knows it doesn't exist), or unsure, meaning that aimake does not know whether the object needs rebuilding (or that it definitely does need rebuilding). Here's what the main loop looks like:
searchfile: objects, in case a generated source file wants to search for the same header file that the source of the generator wanted to search for; the situation is obviously benign, as it'll find it in the same place, but would potentially cause a dependency loop without special casing. The same special case applies in some other situations too; the general rule is that if an object is provided by multiple rules with the same outdepends, only one of them has to be sure.) When the pair is run, it becomes unchanged, and the hashes of anything it previously output, and anything it now outputs, are updated. Such objects also become sure (with a slight exception in the dubious case where the same object is output by multiple pairs). An object no longer being produced by a pair counts as a hash change (the hash of a nonexistent object is treated as different from the hash of an object that exists).
Any warnings produced running the pair are recorded with the pair. If the pair produced an error, then any objects it previously produced are marked as unsure (and cannot be marked as sure again until the rule runs successfully), holding them and all their descendants in limbo until the error is fixed. (If they are deleted from the filesystem in the process, which is quite likely, their hash will also change.) This means that if fixing the error causes the objects to be recreated with the same hash, there will not be a need to recreate their descendants in the future, avoiding the need for a long recompile in the case of a widely depended-on file (like a generator for a generated header file that is included almost everywhere) having an error.
There's one other source of errors: dependency problems. aimake's core doesn't notice a problem if something can't be built due to a missing dependency (it simply assumes it built correctly with no output), but the user probably considers this situation a bug in their program that they would want aimake to tell them about. As such, an internal list is kept of pairs that aren't producing any output; and that list is scanned for pairs that didn't produce output due to missing expanded use dependencies that weren't in the command, to let the user know what went wrong.
aimake tracks a lot more types of objects than just files:
path:One of the files in the source directory. (aimake is designed for out-of-tree builds, although it can build into a subdirectory of the source directory; it simply treats any subdirectory that contains an aimake state file as not existing.) aimake scans these for changes. This is a relative, not absolute, path (so that it continues to work correctly if the source directory is renamed), in aimake relative path format (that is, directories are separated with slashes, and colons, slashes and backslashes in path components are escaped with backslashes; note that aimake relative path format cannot represent an absolute path, which saves having to worry about how the filesystem is rooted). Because they represent specific files, path: objects are produced, not provided.
bpath:One of the files in the build directory: things like object files. Like with path:, this is a relative path in aimake relative path format. bpath: objects are produced, not provided.
spath:One of the files that exists as part of the system's toolchain: compilers, system libraries, system headers, and the like. This is always an absolute path, and is in aimake's absolute path format (which works like its relative path format, except that it has an extra component at the start, which represents the filesystem root to use in a system-dependent manner; this might be the null string on systems whose filesystem only has one root).
spath: objects can only be created via things external to aimake (such as the system's package manager), but they can be produced via a no-op command, to tell aimake to consider them to be relevant; they are considered nonexistent until that happens.
searchpath:A set of directories that is looked in for include files, libraries, or the like. This looks something like searchpath:systeminclude, and the actual paths to search are stored as dependencies (the same way as an optionset: works). Search paths are typically used to produce objects on the search path.
searchfile:A filename that is being searched for (most likely, because there's an unmet dependency on some unknown file with that name). This looks something like searchfile:stdio.h. Note that all objects providing a searchfile: must provide the same list of dependencies for it (the built-in rules create searchfiles with the empty set of dependencies); aimake assumes requests to search for files with a particular name to be interchangeable.
searchlib:A library that is being searched for (not including naming conventions of the platform, e.g. 'libfoo.a' on Linux would become 'searchlib:foo:' and a symbol), followed by a symbol: object that exists within that library. (The symbol has two purposes: ensuring that the correct library is found, and persuading linkers to actually try to link the library while it's being searched for.) aimake assumes that these are interchangeable the same way searchfile:s are.
standardlib:A library that is linked by default. This works the same way as spath: in terms of what file it refers to, but these libraries are omitted from linker command lines, in the knowledge that the linker will link them in anyway. (This is mostly just for neatness on Linux or Windows, but on some platforms, such as recent versions of OS X, it's required for the compile to complete.)
extend:A filename that's produced from another filename. This is formed out of an extension and a file-like object, and is just an alias for something in the bpath:, not an object in its own right. For instance, extend:.s:path:src/foo.c might be an alias for bpath:src/foo.s. (This is mostly used to tell compilers and similar tools where to place their output.) As a special case, an extension of ".." causes the filename to be deleted too, producing the directory of the object: extend:..:path:src/foo.c is path:src. This construction might produce an spath:, path: or bpath:. As another special case, an extension of "..." produces the filename by itself, removing the directories, and producing an output in the root of the bpath:. Finally, an extension of "/" causes a file (which should be in the path:) to be placed in a directory with its own name: extend:/:path:src/foo.c is bpath:src/foo.c/foo.c. (aimake uses this last case internally, to avoid filename clashes, and because many system toolchains work at the directory level, not the file level.)
extend: can also extract the inside object name from a symbolset: or dependencies: object, e.g. extend:.o:dependencies:foo:path:foo.c is bpath:foo.o.
file:A reference to a file with a particular name. This is used to represent dependencies produced via code like #include "foo.h". It is possible for multiple rules to provide the same file: object. (The difference between file: and searchfile: is that if an unknown file is included, that'll produce a searchfile: object to let aimake know to search for it, and depend on a file: object to let aimake know to use it once it's found.)
symbol:A reference to a symbol (as would be used by a linker); this is used the same way as file:, but for linking rather than compiling.
shared_symbol:A symbol that is exported by the file that provides it, and is intended to be compiled as part of the API of a library. aimake's standard rules will attempt to create a symbolset: containing each shared_symbol that is defined.
shared_symbol: objects have their dependencies built cumulatively; if multiple pairs try to generate one, their outdepends will be combined.
direct_symbol:A symbol that is exported from an object file, not a library. This exists in order to avoid an infinite regress in the shared libary code. Anything that produces a direct_symbol: should produce the matching symbol: too.
symbol_in_object:A reference to a symbol produced by a specific object. This is used internally to determine which C files contain a main function.
symbolset:A set of exported symbols, ready to be made into a library. Symbol sets are defined with reference to a filename and version suffix, as in symbolset:.1.2.3:bpath:libfoo. When aimake creates a symbol set, the filename is based on the common prefix of the source files that define those symbols, and the version number on AIMAKE_ABI_VERSION macros in the source files that define those symbols. Symbol sets are provided objects; they don't represent a file on disk (thus, the filename is a suggested filename that will most likely be used to represent the resulting library, most likely with the extension changed to something platform-specific like .so or .dll.). If a symbolset: object is used in an optpath: or extend: object, it will be treated as if it were just its filename portion; this does not happen for other uses of symbolset: objects.
The dependencies of a symbolset: object are built cumulatively; if multiple pairs try to provide the same symbolset:, it will result in one symbolset: with the combined dependencies of all of them. This is how multiple symbols are bundled into one library.
config_option:An option in the config file. This is mostly used in dependencies, to specify things like "this object file needs to be rebuilt if the CFLAGS change" (a build dependency), or "_aimake_get_option.c has the install path substituted into it at compile time" (a use dependency). The object is named using the option name after config_option:, e.g. config_option:CFLAGS. These dependencies are added automatically when options are substituted into commands.
config_rule:A rule in the config file. Every rule implicitly includes itself as a use dependency. That way, if the config file is changed, files are recompiled accordingly. Each rule has its own name for this purpose.
hash_on_disk:Generated as a dummy output dependency of produced objects to record the hash of the file on disk that they created; these objects are used to detect when a file is modified on disk outside aimake. These objects should not be used except via aimake's engine internals (in particular, they should not appear in any part of a configuration rule, because this will not give the desired behaviour; these objects will be ignored as build or use dependencies, and never exist as objects of a rule).
sys:Things like dummy targets, file-like objects that aren't files, and so on. The following sys: objects exist:
sys:always_rebuildAn object that conceptually changes with each run of aimake. This should only be used for, e.g., "last build" reports in the About box of a program. (aimake also uses it internally to determine when to scan for new files in the source tree, a task that should always be performed.)
sys:rebuild_lateAn object that conceptually depends on everything that doesn't depend on it. This is typically used for wildcard-style build rules where you want to depend on everything that obeys a particular pattern. This is implemented via marking it as unsure until no further compilation is possible, then marking it as sure and continuing the compile. If you also need the rule to re-run every time (which is likely when doing wildcard-style dependencies), also add a dependency on sys:always_rebuild.
sys:installingAn object that conceptually depends on everything that doesn't depend on it, including sys:rebuild_late. This is used to ensure that installing is performed last of all, and is implicitly added as a dependency of install rules. (It is probably a bad idea to add it manually.)
sys:cleanAn object that is always sure and never exists. Any rule that depends on sys:clean can run "successfully", causing it to delete all its outputs. It's rare to use sys:clean in a configuration rule manually; rather, aimake will add it to dependency lists automatically when it's required to clean up after a rule is changed, or after a command starts producing a different set of outputs, and thus although it has defined semantics, it's likely best to treat it as internal use only.
sys:touch_onlyAn object that conceptually represents a file that is deleted immediately after being installed. It can be installed in a directory to force the directory to be created at install time. Changing its permissions changes the permissions of the directory.
sys:create_subdirAn object that conceptually represents a subdirectory. It can be installed in a directory, with a specific name, to force a subdirectory with that name to be created at install time (if it doesn't already exist).
sys:empty_fileAn object that conceptually represents a zero-length file. Its only use is to be installed, creating or truncating an install target. (This could theoretically be implemented in terms of intcmd:writefile, but that would be rather unintuitive and hard to read.)
sys:ensure_existsAn object that conceptually represents the file that already exists at an install target. When installed, it will ensure that the install target exists (by creating it as a zero-length file if necessary), but will not overwrite an existing file at that location.
cmd:Represents a command shipped with the system, like gcc. This is only meaningful in the part of a configuration file that specifies what command to run to accomplish something. (bpath:, tool: and intcmd: objects can also be used in the same context.) This is just a filename, no directories are involved, and it omits any extension that might be customary for executables on the platform (thus cmd:gcc has the same meaning everywhere).
tool:A type of command shipped with the system, such as tool:c_compiler. These are provided by cmd: objects, and are typically listed in use dependencies of files that need compilation.
intcmd:Represents a command that's emulated by aimake. This gives system-independent behaviour for some commonly used commands:
intcmd:nopAn internal command that does nothing and produces no output. Typically used in dependency rules that cause a particular object to unconditionally depend on another object, with no complex computation of object names needed.
intcmd:catAn internal command that just outputs the file given as its argument. (The file will be assumed to be encoded in UTF-8, regardless of the encoding of the operating system.)
intcmd:echoAn internal command that outputs its arguments, separated by spaces. Any optpath::s in the arguments will be output in aimake format.
intcmd:echo can also output the content of files, or extract parts of object names, even if they aren't paths:
optpath:-w:The whole object name (for file-like objects, equivalent to not specifying the -w, but it works on other types of object too);
optpath:-q:The file that a file-like object represents, in whatever path format is standard for the operating system you are using, formatted as a C string (i.e. surrounded with double quotes and with special characters escaped).
optpath:-t:The object type, without the colon (e.g. optpath, intcmd);
optpath:-a:The object argument (as would be generated by an outputarg specifier in a rule); this is the bit between the colons for a nested object, or the entire object name apart from the type for a simple object name.
optpath:-i:The "inside" object (the part after the second colon for a nested object); do not use this for non-nested objects.
optpath:-c:The contents of the file that an object represents. (Remember to add a dependency on the file!)
intcmd:writefileAn internal command that takes a filename (as an optpath::, i.e. no prefix) and a set of contents for that file (as any number of optstring:s, or optpath:s with a prefix, which are interpreted as for intcmd:echo.) Any underscores in the contents will be replaced with spaces, and any spaces with newlines, and then the resulting string will be written to that file (which should be in the bpath:); underscores and backslashes can be escaped with backslashes. This is used to generate things like input files for compiler tests.
intcmd:symlinkAn internal command that causes each of its output arguments (optpath:-o:...) to become an alias for its input argument (optpath::...). This will be done via a symbolic link if possible, but on some platforms it may need to copy the file; thus, there is no guarantee that the two arguments will have the same meaning forever. This will overwrite its second argument if necessary. (On POSIXy systems, this is similar to ln -sf, except that it handles relative paths more intuitively.)
intcmd:assert_equalAn internal command that compares two arguments (optstrings or optpaths). It succeeds if they are equal, and fails otherwise, producing no output. The intended use of this command is in combination with fail_silently, to create rules that work only in certain circumstances (e.g. on specific OSes).
intcmd:testcaseAn internal command used for testing aimake. It prints its arguments to the user and records them as warnings, and errors out if the first argument contains "failed" anywhere. There shouldn't be much of a need to use this in anything other than a testsuite for aimake itself.
intcmd:testruncountAn internal command used for testing aimake. It writes the number of times aimake has been run with the current aimake.objects file to a file given as an optpath:. (The main use of this in testing is to allow the construction of a rule that has a side effect upon being run twice with nothing changing.) This command is unlikely to be useful except in testing aimake.
intcmd:optionvaluesAn internal command that takes config options as its arguments (e.g. optpath::config_option:packagename), and outputs their values. An optstring: can be used to specify what format to output them in:
optstring:--equalsValues will be output in the form name=value form. Any values that are aimake objects that represent files will be converted to pathnames as the operating system understands them. No quoting will be used. This is the default, if no optstring is given.
optstring:--structValues will be output in the form {"name", "value", -1},. The names and values will be quoted according to the rules of C strings. Any values that are aimake objects that represent files will be converted to pathnames as the operating system understands them; however, on Windows, if the file is in a known folder directory, the value will be the path relative to that directory, and the -1 will be replaced by the name of a constant representing the name of that directory (such as CSIDL_PERSONAL). This format was designed for the implementation of aimake_get_option, but can be used directly if necessary.
optstring:--optstring-escapeThis option can be given alongside one of the others, and causes the output to be escaped suitably for intcmd:writefile (i.e. replacing underscore with backslash-underscore, space with underscore, newline with space).
intcmd:podformatAn internal command that formats documentation. Its only argument is an optpath:, which represents a file in Plain Old Documentation format (see perlpod for details). This file will be translated into an appropriate format for your operating system: a man page on UNIX-like systems, and HTML on Windows. The output filename will depend on details of the input, so it will be output on standard output, so that you know where the output was placed.
The input should contain two lines to indicate to aimake where to put the file: "=for aimake manualsection section" to specify which manual section it goes into, and "=for aimake manualname name" to specify what the manual is talking about. (As usual for POD, they should have a blank line before and afterwards.) Alternatively, "=for aimake eula" will cause the file to be marked as a license agreement (you can only have one such file), and with some install toolchains, shown to the user for acceptance before installation will happen.
intcmd:filetestAn internal command that takes an optstring: and an optpath:, and either succeeds or errors out depending on information about the filename referred to by the optpath:. The optstring: can be:
-eThe filename exists and refers to something (which might be a file, directory, special file, symlink, etc.; aimake won't check what sort of entity the filename refers to).
-fThe filename refers to an ordinary file.
-dThe filename refers to a directory.
-lThe filename refers to a symbolic link.
-xThe filename refers to an executable. (Depending on the operating system, this might check whether the filename has permissions that allow the current user to execute it, or it might check the filename for extensions like .exe.)
-zThe filename refers to an empty file.
-sThe filename refers to a nonempty file.
-TThe filename refers to a text file. (This cannot be checked 100% reliably.)
-BThe filename refers to a binary file. (This cannot be checked 100% reliably, either.)
intcmd:listtreeAn internal command that takes any number of directory names as its arguments, and returns a list of all the files (but not directories) recursively inside those directories, one per line. (As such, it's similar to the POSIXy find.) Any symbolic links found are returned, but not dereferenced or followed. Unlike calling commands external to aimake (whose output is typically split on newlines before being fed to the regular expression specified in the config file), an internal mechanism is used to remember where the boundaries of each filename are, so this will work correctly even if, for some reason, your filenames contain newlines, NULs, or other such bizarre characters.
If given an optstring as well as an optpath, the optstring specifies the maximum nesting depth to go down the tree; 0 will just list the directory itself, 1 will also list its subdirectories, and so on.
If given an optpath that's a searchfile: rather than a directory, the output will be limited to files with that filename.
intcmd:xuse_statisticsAn internal command that outputs some information about the rule that caused it to run (specifically, the expanded set of use dependencies of the rule's commands, i.e. the build dependencies of its output). Any number of optstring: arguments can be given; they should be of the following forms:
Only objects matching the regex will be included in the output hash. Do not include the slashes around the regex.
The command will fail unless at least one expanded use dependency matches the regex. (The intended purpose of this is to detect when a rule will have no useful effect, e.g. the creation of a library with no object files, in combination with fail_silently.) Do not include the slashes around the regex.
The output is a number of lines in key=value form, and may be expanded with extra information in future. At present, the currently output keys are:
The MD5 hash (in hexadecimal) of the string constructed by sorting then concatenating the names of all the objects (that match the regex given by the -s option, if present) in the expanded use dependencies, separated by colons. The main purpose of this is to be able to easily compare sets of dependencies.
The longest common prefix of the namehint:s in the expanded use dependencies of the rule; any final slash will be removed, and the resulting object name will be on the bpath:. The intended purpose of this is to find a sensible filename and location for objects that would not otherwise have an obvious filename.
The numerically largest observed version number among the namehint:s in the expaned use dependencies of the rule, with a leading dot (this makes regexes that manipulate version numbers easier to write).
A use dependency of the rule's commands, including non-file-like objects, objects on the spath:, or objects that do not match the suffixes given.
optstring:An optstring: object represents an option that needs to be provided to a command. So for instance, the ar command often used to make libraries might have optstring:cr as a use dependency. optstring: objects are the first thing to appear on a command line when a command is executed, and normally start with an appropriate option character for the system (typically slash on systems that don't use slashes as path separators, and hyphens otherwise). These are specified as use dependencies, but become build dependencies unchanged.
optstring: objects are split on spaces, because typically the only use for spaces inside an option is to specify a filename which contains embedded spaces, and that would be done via optpath:. Each space-separated component becomes a separate command-line argument.
An optstring: that has a leading space is moved to the end of the command line, but otherwise works like the optstring: without the space. This is mostly used for libraries, e.g. optstring: -lm.
optpath:A combination of an optstring: and a file-like object. The format is, e.g., optpath:-o:bpath:file.h if they should be combined into one command-line option, and optpath:-o :bpath:file.h (that's a space and a colon) if they should be left as two consecutive command-line options; to just mention a file with no prefix, use optpath::bpath:file.h. (Many fields of configuration rules will fill in a missing object name with the pair's object; thus, optpath:: is a common sight in a command, to substitute a pair's object into its command line.)
Like an optstring:, an optpath: with a leading space (e.g. optpath: -o :bpath:file.h, or even optpath: :libm.so) is moved to the end of the command line, but otherwise works like the optpath: without the leading space. (Specifically, the order of arguments is optstring:s with no leading space, optpath:s with something between the colons and no leading space, optpath:s with nothing between the colons, optpath:s with a leading space, and optstring:s with a leading space.) Apart from this sorting, aimake will try, as far as is meaningful, to leave options in the order in which they were specified.
optionset:A set of options commonly used together, such as the CFLAGS commonly used by make programs (which would be optionset:CFLAGS).
The dependencies of an optionset: object are built cumulatively, the same way that the dependencies of a symbolset: object are. This is useful if you want to combine all files output via a certain rule into an archive.
namehint:A clue as to what would make a sensible name and version number for an object. Objects that particularly strongly hint at a name depend on their own names; e.g. a file bpath:main_c.o that contained the main routines for a file might well depend on namehint::bpath:main_c.o. For objects that hint at creating libraries, a version number is needed too: namehint:1.2.3:bpath:library.c. namehint: objects always exist (thus depending on them doesn't cause problems, unless someone adds dependencies to them using dependency rules; don't do that), and are added by the default configuration according to some heuristics. Therefore, you should never need to deal with them yourself.
dependencies:The set of dependencies generated by a particular dependency rule, e.g. dependencies:ch_file_dependencies:path:header.h would represent the dependencies of header.h that were found via the rule ch_file_dependencies. Dependency objects generated by dependency rules are automatically added as dependencies of the objects they are dependencies for. These can be generated manually too, in which case they behave like optionset: objects; you might want to do this if, for instance, you only want the object to respect certain set of dependencies for the purpose of specific other rules, or if you want something that works like an optionset: but which is parameterized on an object name.
aimake is designed not to need configuration on simple projects, but sufficiently complex projects may need some configuration to explain things to aimake that it couldn't possibly guess (such as how to generate files that are used as part of the build process).
Much of the workings of aimake are driven by a configuration file that's embedded into the aimake script itself, in order that only a single file need be shipped. Any part of this script can be overriden by a configuration file aimake.rules in the root of the package source directory, via specifying an option or a rule with the same name.
The format of the configuration file itself is Perl object notation; this allows for comments, dictionaries, lists, numbers, strings, and regular expressions:
# this is a comment, from the # to the end of line
4 # a number
'abcde' # a literal string
"x\n\t$var" # a string containing escapes and/or variables
qr/foo.*bar/i # a regular expression (qr//; the i is a modifier)
[1, 2, 3, 4,] # a list, trailing comma optional
{foo => 1, bar => 2,} # a dictionary, trailing comma optional
Whitespace is ignored, except inside strings.
The configuration file allows defining one or more variables (either to abbreviate what would otherwise be repeated code, or to avoid "magic numbers" in the code). There are also some predefined variables, which hold platform-specific extensions: $exeext (executables), $objext (object files), $libext (static libraries), $dllext (dynamic libraries), $impext (import libraries; on many systems, this is the same as $dllext because the dynamic libraries are their own import libraries, but on some systems it differs); there is also $symbolprefix, which is an underscore on systems in which symbols have their names prefixed with underscores in libraries, and an empty string otherwise, and $pointerbits, which allows the rules to learn whether they're running on a 32- or 64-bit platform. (In order to catch mistakes due to omitting $exeext, it will never be set to the null string, but rather to an arbitrary string on platforms that do not normally use a special extension for executables. This extension will be removed when installing the executable.)
After any variable definitions comes the main body of the configuration file. This is a single dictionary, which can contain keys options, features, libraries, directories, tests, and rules. rules is the most complex, and documented in "RULE SYNTAX"; tests is currently undocumented because the API is subject to change; and libraries was documented earlier in "Linking in additional libraries". The other sections are documented below.
Here's a simple example aimake.rules:
$version = "1.2.3"; # variable definition
{
options => {
packagename => 'configexample', # override an option
},
features => {
large_data_files => { # define a feature
description => 'Generate large data files',
object => qr/^path:datagen\.c$/,
default => 0,
},
},
rules => {
install_executable => undef, # undefine a rule
_generate_usage => { # define a new rule
command => ['extend:$exeext:bpath:gendocs', 'optstring:-u'],
output => 'bpath:doc/usage',
},
},
}
The options dictionary is very simple: keys of the dictionary are options, and the corresponding values their values. The following options are recognised (unrecognised options are also legal, but will be ignored except for config_option: dependencies):
A name that identifies the package. If the build layout requires files or directories to be given names specific to the package (to avoid clashes with other packages), this name will be used as the filename. This is intended for use in automation, and so does not have to be user-friendly (but does have to be unique), although it may be shown to the user in package archives and the like. Legal characters include lowercase letters, digits, hyphens, and underscores (although by convention, hyphens are reserved to provide namespaces, e.g. foo-plugin-bar might be used for a plugin for a package foo).
The default is the name of the directory holding the source files.
A name that identifies the package. Unlike packagename, this can contain spaces and punctuation. It will be used when defining metadata of installed files.
The default is to copy the packagename option.
A name that identifies the package. This is used in cases where a system shows filenames to a user directly. This can only contain characters which are legal for filenames in all supported platforms, but has more latitude; in addition to legal characters for a packagename, it also permits uppercase letters, spaces, commas, and periods.
The default is to copy the packagename_text option if it contains only legal characters, and otherwise to copy the packagename option. Thus, this option will rarely need to be set explicitly.
The package's version number. This is a string that contains a sequence of numbers (of up to four digits), separated by dots (e.g. "1.0.0"). Components other than the first can also be of the form "alpha" or "beta" followed by a number, e.g. "1.1.beta5"; this will be converted to an appropriate format for your operating system that sorts before "1.1.0" but after "1.0.0". It is currently used when defining metadata of installed files, and to let installers know when a file has upgraded (if you want upgrades from one version of your package to another to work, you must increase the version of the package and all files with each new package, and this increase must occur within the first three components); in the future, it may also be used to avoid clashes between different versions of the same package, on some operating systems.
The default is "0.1".
The organization that produces this package. The default is to append a space and "developers" to the packagename_text option.
A regex of directory names to never consider part of the source tree. (By default, this is a list of directories used to hold data by a range of version control systems.)
A list of filenames that cause directories containing them to never be considered part of the source tree. (By default, this is a list of files generated to hold internal state by autoconf, CMake, and aimake, which indicate that the directory is being used as a build directory.)
A regex of filenames to never consider part of the source tree. (By default, this is a list of filename patterns used for backup, autosave, and similar files in a range of editors.)
Features are dictionaries with the following keys:
A description to show in the --with=? help output, and similar places where a user-readable description of what the feature does is needed. This should be less than a line long, and will be used for UI elements where there is limited space (e.g. entries in a menu).
Serves the same purpose as description, but allows considerably more text. This is used for UI elements where more space is available (and will typically be on-screen at the same time as the description). This should not contain newlines, but will be wrapped on spaces in order to fit it into the space available for it.
A regular expression matching objects that are considered to be part of the feature. If the feature is turned off, aimake will refuse to consider any source files that match the expression as existing. Other objects that match the expression will be disregarded when output, but will still be considered to exist if they already exist (due to a previous aimake run where the feature was turned on) and do not need rebuilding. (We are considering changing this rule in future versions of aimake. For the time being, it's best to use this only to match path: objects.)
If you want the feature to only have an install-time effect, rather than a build-time effect, you can use the regex qr/(?!)/, which matches nothing.
Set this to 0 for the feature to be off by default, or 1 for the feature to be on by default.
The name of another feature. This feature will not be built or installed if a feature it depends on is not built or installed. This is optional, and can be omitted. (Each feature can only depend on a single other feature, although more than one feature can depend on a given feature; thus, the features form a "forest", a tree that can potentially have more than one root. The implicit root of the tree is the package as a whole.)
When installing files, aimake will determine which directory to place each file into based on two factors. One is the install_dir field of the rule that installs the file; this specifies a directory logically, such as bindir. The other is the directory layout in use, which is specified by the --directory-layout and -i options.
aimake's built-in configuration file specifies many directory layouts in its directories dictionary. You can create directory layouts of your own, too. Each key of the directories dictionary is the name of a directory layout; the corresponding value is a dictionary that specifies the layout itself.
A directories layout has two special keys, autodetect and preferred_installdir. These both handle the case where the user specifies only one of -i and --directory-layout. The autodetect key is a regular expression that matches an aimake-syntax filename (e.g. the autodetect key for the fhs layout is qr/^spath:\/(?:usr)?$/, which matches only spath:/ and spath:/usr); aimake will use this layout for an -i option matching the given regular expression. The preferred_installdir option is an aimake-syntax filename, that specifies a default value for the -i option in the case where only --directory-layout is given.
The other keys are all directory names ending in dir, as aimake-syntax paths. These can also substitute in the values of other directory names (or installdir, the argument to the -i option), e.g. the fhs layout sets bindir to $installdir/bin, staterootdir to spath:/var, and logdir to $staterootdir/log. Note that these should be single-quoted in the configuration file (i.e. bindir = '$installdir/bin'); otherwise, they will be confused with a variable substitution using a variable from the configuration file.
The rules dictionary is the most complex part of a configuration file. It consists of a number of rules; the keys are the rule names, and the values the rules themselves. aimake's predefined rules will all start with a lowercase letter. In order to avoid clashes with them when defining your own rules, start the names of your own rules with an underscore.
A rule itself is written as a dictionary. The keys of the dictionary specify information about the rule's dependencies and how to run it; what messages the rule produces; how to parse its output; and what to do after it has been run.
All of these fields are meaningful for any rule.
Although there are only finitely many rules in the configuration file (and in aimake's internal configuration file that specifies the built-in rules), there can be an unlimited number of pairs; a rule can run multiple times, each time applying to a different object.
The object field allows a rule to be parameterized by an object. It can either be a string (to have only one copy of the rule, always parameterized by the same object), or a regular expression (in which case there will be a copy of the rule for each object that matches, each leading to a different pair). The default is to use a hardcoded sys:no_object.
Each pair that shares a rule has some fields parameterized by its object. Any object names that are left unfinished (such as optpath:-i :) have the object substituted at the end of them (so if the object was bpath:foo.txt, this would be equivalent to optpath:-i :bpath:foo.txt). The default value of inner is also equal to the object, meaning that fields such as output and depends have this substitution performed on them by default, too; unlike the command, though, this behaviour can be overriden via explicitly setting inner.
The object is also the object that has dependencies attached to it via rules that use the depends field in order to attach use dependencies to objects "after" they are generated (although this is just a complex form of syntactic sugar, as explained above).
For convenience, the object is implied into the command by default in many cases (because this is normally what is wanted); see the description of the object_dependency field. This behaviour can always be overriden via changing object_dependency.
Some types of object are disallowed in the object (basically either because infinitely many of that object exist, or because the object is entirely virtual, or because aimake doesn't track how many of those objects exist): sys:, cmd:, intcmd:, optstring:, optpath:.
The command has two purposes: it specifies the build dependencies of a rule, and also which command must be run in order to execute the rule. This is a list of objects (if it has length 1, the [] surrounding the list can be omitted, and the single object specified will be treated as a 1-element list). The default value is a list consisting only of intcmd:nop.
The build dependencies of the rule are calculated via starting with the command, and recursively expanding it with the use dependencies of the objects in it, their use dependencies, and so on. The executable-like and option-like objects in the resulting list are also interpreted as a command to run in order to execute the rule.
A null string in the command of a dependency rule refers to the object (which must be given). This is, however, mostly pointless; the object is automatically implied into the list whenever it would not lead to an infinite regress, with the default value for object_dependency. Likewise, if just the "outside" part of an object (e.g. optpath::) is given, the object is used to fill in the "inside" (and this can be meaningful in any sort of rule). Note that just because the object is automatically included in the dependency lists, this doesn't necessarily mean it will be mentioned on the command line (given that the object is not an option-like object); use optpath:: for that. The command line arguments to the executable being run are produced entirely out of optstring: and optpath: objects; no other objects have an influence on it, unless you consider the name of the executable itself to be part of the command line.
Typically speaking, the contents of a pair's object matters to the pair's command; the object must be up to date before anything can be produced or provided from it. Sometimes, a provision (or in extreme circumstances where only the object's name is relevant and its contents irrelevant, a production rule) rule will not need the normal use dependencies of an object to be in place. (For instance, when looking at a file to see which symbols it provides, you don't need access to the symbols that that file uses.)
The object_dependency field of a rule allows control over where the object is included. Its value is a string:
The object is included in the command if all the rule's actions are provision, production, or install actions; and not included anywhere if all the rule's actions are dependency actions. In other cases, this value is an error. object_dependency => "auto" is the default.
The object is included in the outdepends of any provision actions of the rule. This allows the use dependencies of the pair to be "deferred" one level; they don't need to be in place to run the rule, but they do need to be in place to make use of the rule's output.
The object is not automatically included anywhere, perhaps because it works differently for different actions of the rule (you can get something equivalent to object_dependency => "outdepends" via adding a null string to an outdepends list). This is mostly useful when the object's use dependencies are truly irrelevant, such as when providing searchfile: objects.
By default, aimake uses absolute paths for command line arguments. Sometimes, a program will only function correctly with relative paths. In such a case, set in_subdir to specify the current directory for running the command; optpath:s that refer to files within that subdirectory will be formatted as relative paths.
This option can also be used simply to make command lines shorter, making them easier to read in error messages. In such cases, it would typically be set to bpath:.
Sometimes, an object can be provided by more than one pair. This is not an error; aimake attempts to choose the most appropriate. Sometimes, though, which object is most appropriate depends on which rule was involved in creating it; in this case, you can set avoid_rules to a regular expression that matches the names of rules. Provided objects created by rules whose names match the regular expression will not be considered to satisfy dependencies of this pair; and produced objects created by rules whose name match the regular expression will not be considered as an object of the rule. (You would use this, for instance, to avoid an infinite regress when creating a dynamic library; you would want the symbols to come from object files, not from the dynamic library that the rule itself had created.)
avoid_built_from works like avoid_rules, except that it excludes provided objects only, and is based on the object they were built from, rather than the rule they were built from. This is a single object name, which will have missing portions filled in with the object the same way as with the command. (For instance, this is used in the scenario where a source file produces an implementation and an interface in separate files, and compiling the implementation needs access to the interface of other files; it should not be compiled in terms of its own interface, or it will attempt to import from itself, which typically leads to problems.)
Setting force_locale to a particular value forces the LC_ALL environment variable to have that value while running the command:. This is used when the rule needs to parse human-readable output from the command; many commands will vary their output depending on the locale, typically to translate it into the user's language. The usual value for force_locale, when needed, is "C"; this value is defined to be supported by every program, and designed to cause them to try to make their "human-readable" output as machine-readable as possible: messages are written in a default language (normally English, or a terser version of English), numbers are written with a period as the decimal separator and no grouping marks, and so on.
The locale is also used to work out what character encoding a program's output is likely to be in, in order to correctly convert it to Unicode for regular expression matches.
If set to a nonzero integer, aimake will consider the command to have errored out if any regexes in the rule fail to match any lines of output. (This helps detect typos in regexes, or unusual output formats from the command you're regexing, in the case where you know that correct operation will cause the regex to match at least once.) This option overrides on_failure in the situation where both are given.
These values can be set for any rule, and have no effect on anything but the messages displayed to the user.
low_message_priority is an integer, defaulting to 0. If this is set to a nonzero value, it causes aimake not to print messages about this rule being run unless the verbosity level is increased to at least 1. (This is used for production rules that make aimake aware of objects on the spath:, mostly.) There is no point in specifying this for rules which consist entirely of dependency actions, because those messages require a verbosity level of 1 or more to be printed anyway.
debug_trace is sort of a conceptual opposite of low_message_priority; however, unlike that field, it is mostly only useful for debugging aimake rules files, and should not be used in production use. If set to a nonzero integer (the default is 0), it will cause aimake to print debug information concerning the rule in question; aimake will print a message when the rule starts to run and finishes running, and the command line and output of any commands that it runs, even if the verbosity level is at 0.
ignore_warnings is an integer. If set to a value other than its default of 0, any warnings produced while running the rule's command will be discarded, rathe than shown to the user as is normal. This is mostly useful when you know that the rule will produce spurious warnings in some situations.
(If you actually wanted to react to the warnings, rather than just hiding them, see the also_match_stderr field.)
hide_errors works like ignore_warnings, but instead of discarding warnings, it "discards" errors when set to a nonzero integer. The errors nonetheless happen, and on_failure is respected like normal; they just aren't shown to the user.
The default value is normally 0, but it defaults to 1 if any actions of the rule have their on_failure fields set explicitly in the rule, or if the on_failure fields are set to auto and the program produced error output that caused this to resolve to inapplicable rather than the default of fail. It can be overriden explicitly to 0 if required, or explicitly to a nonzero value if required. Note that overriding this to 0 will cause the build to fail if any errors occur, even though on_failure handles the resulting errors, and thus this combination is probably not very useful.
verb affects the message given (e.g. "Built file.o") when a pair fails or succeeds, and can be used to make aimake's output a little more user-friendly than normal; most built-in rules have an appropriate verb, and you can set it in your custom rules, too. The default depends on what actions the rule takes upon succeeding, typically "built" or "found".
Although many of the internal commands (i.e. an intcmd: object that's directly or indirectly included in the command) are very well-behaved, using an internal mechanism to remember rule boundaries and with no encoding issues, commands external to aimake are rarely so well-behaved. The fields in this section instruct aimake to perform various processing on the output before the rule's actions match it with regular expressions.
If filter is set to a regular expression, aimake will disregard any lines of output that do not match the regular expression.
Setting linesep changes what is considered to be a line separator in the output. You might, for instance, want to split the output on spaces if trying to parse a Makefile rule. The default is a newline ("\n"). This can be a regular expression, or a string (which is matched literally).
If linesep is combined with unescape, then escaped literal newlines will be deleted (as usual with unescape, escaped lineseps will be considered to be a literal linesep, unless linesep is a newline itself), non-escaped literal newlines will be considered to be newline characters that don't break a line, and non-escaped lineseps will be considered a transition from one line to the next. (This makes it possible for every codepoint to be used in the output from a program; as such, aimake will track the line separators internally.)
After applying the filter and linesep, specifies the first line of output that will be read, by specifying how many of the lines to skip at the start (as an integer). The default is 0.
After applying the filter, linesep and lineskip, specifies the maximum number of lines of output that will be read (as an integer). If not provided (the default), all the lines will be read.
When set to a string, causes aimake to unescape the output from a program. By default, no unescaping is done. At present, the only recognised values for unescape are:
'backslash'Backslash-newline is deleted; backslash followed by any letter in abfnrt will be replaced by a corresponding control character according to the rules of C; and backslash followed by any other character will be replaced by that character. (No vertical tabs, sorry. They're not portable between character sets. At present, we don't implement decimal/hexadecimal/octal escapes, either.)
'backslash_whitespace'Backslash-newline is deleted; backslash followed by other whitespace, or another backslash, deletes the backslash but leaves the whitespace or second backslash; and backslash followed by any other character preserves both the backslash and the character. (This is the encoding gcc uses for makefile fragments.)
If set to a nonzero integer, causes the command's output to be considered to include standard error as well as standard output. (That is, messages on stderr will not be considered to be warnings, but rather will be matched by any regular expressions used.) If left at its default value of 0, anything printed on stderr will be assumed to be a warning or error message, rather than the part of the program's output that regular expressions are trying to match.
After a rule is run, it can produce objects, provide objects, add dependencies to objects, or install files — or any combination of these (except that installing must be done on its own, because it might need special permissions). If a rule only has one action, the fields that describe that action can be placed into the rule's dictionary directly. Otherwise, each action has its own dictionary, all of which are specified using the actions field.
If a rule has more than one action, they cannot be specified directly in the rule's dictionary, because then their fields would get muddled with each other. Rather, each action has its own dictionary. The actions field takes a list of these dictionaries as its value.
For example, a complete rule might look like this:
foo_c_includes_foo_h => {
object => "bpath:foo.c",
object_dependency => "nowhere",
actions => [
{ depends => "file:foo.h" },
{ output => "searchfile:foo.h", outdepends => [] },
],
}
This rule has a provision action, and a dependency action.
A rule can contain any number of provision actions, any number of production actions, and up to one dependency action; alternatively, it can contain a single install action (in which case using actions is pointless; you could simply specify the install action directly).
Available for: any sort of action
Normally, aimake will automatically attempt to determine which sort of action is which, by looking for the output, outdepends, install_dir, and depends field. However, there is a potential ambiguity in cases where both output and outdepends are specified. aimake will assume that such actions are provision actions, by default; in the case where this is actually a production action, an explicit actiontype => 'produce' must be given.
Any type of action can have an explicit actiontype setting that specifies the type of action explicitly: the action types are provide, produce, depend, and install.
Available for: provision actions, production actions
The output field is used in provision and production actions to specify which objects are created as a result of running the rule. This can be a single, hardcoded string; a list of hardcoded strings; or a regular expression. In order to generate the full names for the output objects, output and outputarg will be concatenated; and if this generates an incomplete object name, a colon (if necessary) and inner will be appended. The action will run once for each element in the list, or each time the regular expression matches, applying to a different element or match each time.
When using a regular expression, the first parenthesized group of the expression will be interpreted as the output object, and in most cases, translated from whatever format your operating system uses for filenames to an aimake object name. The exception is when using an internal command that operates on objects, such as intcmd:listtree; aimake knows that those commands operate on object names, and so the regular expression match will be interpreted as an object name in those cases.
If the action produces a file-like object, aimake will error out if the file does not actually exist on disk. (This is to catch mistakes in the configuration files; it would be less code to permit this case, but it is unlikely to be what was intended, and seem to have no purpose.) The file does not actually have to be created by the command; especially in the case of path: and spath: objects, it's sufficient for the file to be pre-existing (in which case producing it merely lets the file be used as an aimake object).
As a special case, the object is ignored if it appears in the output, because it is meaningless for an object to provide or produce itself, and because it often makes it much easier to write regular expressions to parse output without having to handle that special case.
A provision action requires output; a production action requires either output or output_from_optpath.
Available for: production actions
One very common situation in which a rule is used is that the build system needs to run a command on some set of files, which produces some other file as an output, and a command-line option is used to tell that command where the output goes. Instead of repeating whatever calculation was used to determine the destination filename, you can instead use output_from_optpath to tell aimake to look at the command-line options to find out where the output goes, the same way as the command does. For instance, if the program took an option optpath:-o :bpath:foo.i, you would use optpath_from_output => '-o '; aimake would interpret this as an output of bpath:foo.i. You can give an array here too, e.g. optpath_from_output => ['-o ', '--header='], for if the command has more than one option that controls output locations.
Available for: production actions
Normally, outputting something in the path: or spath: (including standardlib:) is a mistake. If you do it intentionally (e.g. to make aimake aware of files in the spath:), set information_only to a nonzero integer so that aimake will know that you're merely talking about the files, not changing them, and so not error out. The default is 0.
Available for: provision actions, production actions
Provision actions don't generate files on disk; they just say "objects X can be used to provide object Y". In this case, object Y is the output; outdepends specifies what objects X, the use dependencies of object Y, are. This is in exactly the same format as the output, although instead of being concatenated with outputarg and maybe inner, it uses dependsarg and inner instead. outdepends is required for provision actions (although it can be set to an empty list []). It can also be used with production actions; this is typically only useful when the way in which an output file must be handled depends on which rule was used to produce it, a situation which is rare but not unthinkable.
Available for: dependency actions
A dependency action adds a set of use dependencies to object. This specifies those objects. This works exactly like output and outdepends, using dependsarg and inner. This must be set for dependency actions, but not for any other sort of action (it's the field that distinguishes a dependency action from other types of action).
Available for: install actions
An install action causes the object to be installed in a given directory. This must be given for install actions, and only for install actions, and takes one of the following strings as its value:
A directory used for installing executables runnable by the user. When installing system-wide, this will typically be somewhere that's on the $PATH by default (except on Windows, where there are no suitable locations, and so a project-specific subdirectory of Program Files is used by default).
A directory used for installing libraries that are used by tools provided with the system, such as C compilers. This should be used for architecture-dependent files.
A directory used for installing libraries that are only used by the program being installed. Like libdir, this should be used for architecture-dependent files.
A directory used for installing include files that are used by tools provided with the system (e.g. C header files). This should be used for architecture-independent files.
A directory used for installing architecture-independent include files that are specific to the program being installed (although they will still be visible to system tools if an appropriate path fragment is used when including them; this does not cause the files to be secret, it simply tries to namespace the files to avoid filename clashes).
A directory used for system-wide configuration files (that apply to all users on a multi-user system); these may be intended to be edited by the user, but should not be edited by the program itself. These should be text files.
A directory used for general architecture-independent read-only data files used by the program.
A general-purpose directory used for documentation, when no more specific directory is available. Use this directory for documentation in unusual formats.
A directory used for documentation in UNIX manual format. These directories are often divided into sections, in which case aimake will automatically place installed files into the correct section.
A directory used for documentation in GNU Info format.
A directory for installing source code.
A directory that contains descriptions of executables and is typically used to show a menu to run them (e.g. the Start menu on Windows, or /usr/share/applications on Linux).
A directory used for general architecture-independent data files that are both read and written by the program (and that are shared between all users).
Note that in many cases, this directory will be administrator-owned; therefore, your program will not actually be able to write to this directory unless it's being run with administrator permissions, or you use the install_permission option in order to grant write permissions to a wider audience.
Like bindir, but for executables designed to be run with elevated permissions. This doesn't actually do anything to elevate the permissions, nor to prevent users without elevated permissions running the executables; rather (on many operating systems) it makes it harder for non-administrators to run the program by accident.
If you want to outright require administrator permissions to run the program, see the install_permission field.
Like bindir, but for executables which are games. (Some sites may have policy that handles game executables specially.)
Like datadir, but for read-only data files for games.
Like statedir, but for read-write shared data files for games (such as high score tables).
A directory used for log files that are written by the program.
A directory used for files, shared between all users, that are transient in nature. (The directory is likely, but not guaranteed, to be one where files are deleted on reboot.) It is probably a bad idea to install anything into this directory, but aimake tracks it so that compiled programs can refer to it via aimake_get_option.
A directory used for files, shared between all users, that are transient in nature, that is not used by any other package (and thus, can be given files with arbitrary filenames without worrying about name clashes). In addition to the warnings under lockdir, bear in mind that the directory itself may be deleted on reboot, and as such, may have to be re-created each time it is used.
Available for: install actions
The basename to install a file under; this defaults to the basename of the object. This can include forward slashes to install into a subdirectory (regardless of what the path separator happens to be on the system in question).
Available for: install actions
If set to 1 to mean true, defaults install_name to the entire path of the object (relative to path:, bpath:, or spath:), rather than just the basename. The main use for this is internal, to allow the installation of source code without losing information about its directory structure.
Available for: install actions
When installing an executable, also generate appropriate OS-specific metadata for that executable (setting its human-readable name, icon, etc.). The format of these parameters as given to aimake is OS-independent, and will be converted into an appropriate form for the OS you are targetting; depending on the OS, this might involve installing extra files, making changes to the files after install, or both.
This option can only meaningfully be set for executables and intcmd:symlink aliases to executables (in which case, a copy will be used rather than an alias if this is necessary to respect the operating system's metadata format).
This option will have no effect on Windows unless the Perl module Win32::Exe is installed. (However, this module is often shipped with Perl interpreters on Windows.)
Note that some operating systems place maximum lengths on individual values here, or on the total length of all values, and aimake may not be able to detect if the maximum lengths are exceeded. You should, therefore, try to keep the metadata values as short as possible.
The value is a dictionary, with the following keys, all of which are optional, and which will be ignored if they do not apply to the operating system in question:
An aimake object that represents a file on the filesystem (such as path:icon.png), or a regular expression that matches one or more such objects. All such objects must be PNG-format images. These images specify the icon that will be associated with the executable; the operating system will pick an appropriate image from the images given based on the size it needs to render the image at (and perhaps rescale it, if no image fits the given size exactly). By default, no icon will be explicitly specified (most likely, the OS will substitute a generic icon).
In order for icons to be usable by all OSes, they must be square, and have one of the following sizes (in pixels): 16, 24, 32, 48, 64, 72, 96, 128, 256. Additional sizes (including non-square sizes) can be specified, but may be ignored.
This option currently does not work correctly on versions of Windows prior to Windows Vista. (However, such versions are by now dangerously obsolete.)
A string that specifies the copyright status of the executable (for example, "Copyright (C) 2014 Alex Smith"). By default, no copyright status will be embedded into the executable's metadata. Not all operating systems have any use for this, so it may be ignored.
A string that specifies the version number of the executable. This should be comprised of dot-separated numbers (e.g. "1.0.0"); some operating systems may disallow more complex version components, or add trailing .0 components (although aimake will handle alpha and beta components the same way as with packageversion, converting them to numbers if necessary). By default, the value will be taken from the packageversion option, but it can be given explicitly to override this (e.g., if different executables have different versions).
For upgrades to work correctly on every operating system, aim to ensure that with every new released version, the version number of every file increases within the first three components. (Defaulting this to the packageversion, and just increasing the packageversion, is the easiest way to do this.)
A human-readable name for the executable. This will be used to name the executable in menus and similar structures, especially when it isn't running (and thus there is no window title that could be used instead). The default is to use the filename with any extension removed.
A human-readable description for the executable. On some operating systems, this will be used as a tooltip for the executable on menus. (Others will just use its name, especially if they have an icon-based rather than text-based menu system, and thus aren't displaying the name anywhere else.)
0 for false or 1 for true. If true, then aimake will attempt to tell the operating system that this application always needs a terminal window to connect its standard input and output to (and thus, if the application is run from outside a terminal, the OS will have to create a new terminal to run it in). If false, then no terminal will be created for the application (meaning that it might not have a standard input and output to use, and thus will need to use some other method of communicating with the user, such as opening a window).
This option has no effect if the application already has control of a terminal (e.g. the application is run using a command prompt that is already open in a terminal), and might not be respected on all OSes in all circumstances (one example of when it isn't is when using the Alt-F2 shortcut that exists in some Linux desktop environmens, which runs a program via filename without reading its metadata and without an existing terminal).
The default is to respect whatever setting the compiler used, or in the case where it didn't specify, 1. (It is quite common for the compiler not to specify, so you should probably set this to the right value explicitly.)
0 for false or 1 for true (default). If true, then aimake will attempt to tell the operating system that it's meaningful to run this application directly, without extra parameters, and that the application will then attempt to interact with the user. If you set this to false, this indicates that the application needs command-line arguments to function correctly, has no visible effect when run, or both; this will cause aimake to try to leave it out of the OS's menu system for running applications.
There is currently no situation in which a non-interactive program would benefit from a description; aimake ignores the description in this case. You may wish to specify the combination anyway in case it ever becomes relevant in the future.
Available for: install actions
This can only be used when installing a directory (i.e. sys:touch_only). This is a string, which will give a user-readable name for the directory (under the same rules for legal characters as the packagename_ui option). What effect this name has will depend on the operating system; on Windows, it will create a Start Menu entry for the directory, and on Linux, it will place a symlink to the directory in the package's documentation directory.
Available for: install actions
A value that causes aimake to adjust the permissions on installed files. In most cases, this refers to who can read or execute the resulting files; in the case of statedir and similarly writable directories, this additionally refers to who can write them.
Options for this field include "ADMINISTRATOR" (only administrators can read/execute/write the files), and "ANYONE" (anyone can read/execute the files, and write files in the statedir). Leaving the field absent allows anyone to read or execute the files, but only adminstrators able to write them. Other values may be understood, depending on the operating system; for instance, "games" is common under UNIX-like operating systems, meaning that the file should only be readable/writable by games, not by players directly; this can be used to protect the integrity of high score tables, for instance.
If a user is installing for their own use (via -i into a directory they own, rather than a public one), aimake will not do any special permissions handling (i.e. install_permission and install_elevation will be ignored); that user will be able to do what they like with the installed files, other users will not be able to write those files (and may or may not be able to read or execute them depending on how that user has configured the permissions on the install directory). Likewise, the --natural-permissions option disables permissions handling.
Permissions are implemented as groups on UNIX-like operating systems (apart from "ADMINISTRATOR", which is implemented using the user with a UID of 0, and "ANYONE", which does not need a user/group to correspond to), and thus only exist where a group with the same name exists. You may need to create the group separately before running aimake. On Windows, permissions cannot be granted by aimake's own install process; however, aimake will communicate information about permissions to other installers, and thus an install via --gen-installer will set permissions appropriately (although any values other than "ADMINISTRATOR" will be considered as synonyms for "ANYONE").
If the permission in question does not exist, aimake will print a warning and substitute the default setting (anyone can read/execute, but only administrators can write).
Available for: install actions
If set to a nonzero integer (the default is 0), causes install_permission to control only write and execute permissions; anyone will be able to read the file. This makes install_permission redundant except on executables or on writable files.
Available for: install actions
A value that causes aimake to attempt to grant permissions to the executables it installs. (Granting permissions to a non-executable is meaningless, and thus ignored.) The values (and system-specific caveats) are the same as for install_permission; an executable with a given install_elevation can read, write, and execute files with a matching install_permission. Thus, if you want to protect a file so that it can only be read/written by means of the executables you install, give the executables an install_elevation matching the install_permission of the file. (Operating-system-specific techniques may be needed to cause the permission to exist in the first place.)
Although aimake supports an install_elevation value of "ADMINISTRATOR", we strongly recommend that you do not do this, because it nearly always leads to security problems unless the elevated executables are very well written.
Available for: install actions
Features (see --with/--without) have a compile-time effect, preventing files being built. However, they can also have an effect on what is installed. If the install_feature field of an install rule is set, that rule will not run unless the matching feature is requested.
In some cases involving --gen-installer, aimake can represent the behaviour of this field inside the generated installer. In such a case, the install rule will not even be included in the installer if the feature is disabled with --without (or having a disabled default); if the feature is enabled with --with (or having an enabled default), it will be included in the installer, but the option as to whether to install the feature will be under the control of the person who uses the installer (and its default value in the installer interface will be the same as the default value of the feature in aimake).
Available for: production, provision, and dependency actions
There are a few compound objects like searchpath: and optpath:. To output such objects, output or depends can be set to just the "outside" part of the object (e.g. searchpath:library: or optpath:-o :), and inner is used to specify the "inside" part of the object. It can be a regular expression, with the same meaning as making output or depends a regular expression. The default value of inner is for it to be the same as the object.
Available for: production actions, provision actions
Nested objects have the form objtype:outputarg:inner. If output is just a objtype:outputarg:, the inner is used to fill in the rest of the object name. If output is just a objtype:, however, the outputarg is used to fill in the rest of the name; this works for both nested and non-nested objects. (It's possible to have both an outputarg and an inner in the case of a nested object.) outputarg should be omitted if not needed, and should be specified if needed. Just as with inner, it can be a regular expression (and typically is only useful if it's a regular expression); unlike with output and inner, it's always interpreted as a plain old string, not as a filename or object name.
Although it is usual to divide up an object name between output and outputarg such that output contains the object name up to the first colon, and the outputarg contains the part of the object name between the first two colons, this is not mandatory; the output and outputarg will be concatenated regardless of what they contain, and interpreted as an object name (or a nested object name missing the inner).
Available for: production, provision, and dependency actions
Works exactly like outputarg, except for depends and outdepends rather than output.
Available for: provision actions
This specifies the name of an environment variable. If the variable is set in the environment, as an option in a configuration file's options, or using the --var option, the outdepends of this action is entirely replaced with the value of that variable. (This is how things like CFLAGS are implemented internally; their default values are specified in a rule which has a command_line_override.)
Available for: production, provision, and dependency actions
If a command fails to run (that is, it reports a failure using its exit code, or it crashes), there are several ways that aimake can handle the resulting situation. The default is always auto, but there are more possibilities than that available, which can be specified separately for each action using the on_failure option:
Normally acts like fail. However, if the string !AIMAKE_FAIL_SILENTLY! is observed in the command's error messages, acts like inapplicable instead (and if hide_errors is not specified explicitly, changes its default to 1). This allows a file to conditionally mark itself inapplicable via using whatever facilities the program interpreting it provides to force an error. For instance, a Windows-specific C file might contain directives like this:
#ifndef AIMAKE_BUILDOS_MSWin32 # error !AIMAKE_FAIL_SILENTLY! This file only works on Windows systems. #endif
If the command fails to run, do not attempt to produce this output, and delete any existing output (for a production or provision action); or do not allow the use dependencies of the object to be fulfilled (for a dependency action). In other words, do not attempt to proceed with the build further if it would require this rule to have succeeded.
Acts identically to fail for a provision/production action, and conditional for a dependency action, except with different messages; the user will be informed that the rule was not run due to the configuration. This also changes the default value of hide_errors to 1, because it is not fail, meaning that an inapplicable rule will not cause aimake to report that the compile failed unless hide_errors is set to 0 explicitly.
If the command fails to run, assume that it succeeded, but produced no output on stdout. This typically works out to the same thing as fail when the output is a regex match (and is not very useful when not using regex matches). However, if the depends/outdepends is a regex match, this can lead to a successful output with fewer dependencies than it would otherwise have; occasionally, this is what you want.
This can only be given for dependency actions, and provision actions whose output is hardcoded (otherwise it would be unclear what to output if the command failed). If the command fails to run, use an empty depends/outdepends rather than the specified depends or outdepends. The intended use of this is to add dependencies conditionally.
This is similar to conditional, but provides more control; if the command fails to run, use the depends/outdepends given in the rule's alternative field, rather than the specified depends or outdepends. This is intended for use in writing autoconf-like tests.
If the command fails to run, parse what output (if any) it produced before it exited or crashed, as if it had succeeded. This setting is useful in the case of commands that otherwise work, but produce a failure code, perhaps because they fail only after they've produced the messages you are interested in.
Available for: provision actions
preference is an integer from 0 to 100, defaulting to 0. When multiple actions (in the same rule, or across different rules) attempt to provide the same object, various heuristics are used to determine which object should be used for any given purpose. preference provides a global tie-break on this, allowing (for instance) aimake's default ruleset to prefer linking against shared libraries than linking against static libraries with the same basename.
Available for: provision actions
Causes any file: objects that would be output to be output as searchfile: objects instead, if set to a nonzero integer.
Available for: production actions
Causes any spath: objects that would be output to be output as standardlib: objects instead, if set to a nonzero integer.
Available for: production, provision and dependency actions
Causes any objects other than file: objects (i.e. any objects that correspond to an absolute path) that would be generated via a regular expression match to be ignored if set to a nonzero integer (this is most common/useful in dependency rules). It should be set to a nonzero integer or omitted.
Available for: production, provision and dependency actions
Causes any spath: objects that would be generated via a regular expression match to be ignored, if set to a nonzero integer. (This is most useful in the case where you aren't interested in dependencies on system headers.)
Available for: production, provision and dependency actions
If set to a nonzero integer, causes any objects that would be generated via a regular expression match to be ignored if they don't appear to be the filename of an existing file (that's either a regular file or a symbolic link). It should be set to a nonzero integer or omitted, and is mostly useful for avoiding false positives when parsing output that mixes filenames with other information.
Available for: production, provision and dependency actions
If set to a nonzero integer, causes any objects that would be generated via a regular expression match to be ignored if they appear to be text files, rather than binary files (the main purpose of this is for filtering out linker scripts, which cannot be distinguished from libraries via filename alone). It should be set to a nonzero integer or omitted. Note that testing whether or not a file is a text file is not 100% reliable (although it tends to be reliable enough to distinguish a linker script from a library, because both are in formats that are easy to test for binary-ness).
Copyright (C) 2013, 2014, 2015 Alex Smith.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Note that the author of this program does not believe that programs compiled using aimake are a derivative work of aimake (in the same way that, for instance, programs compiled using autoconf are not a derivative work of autoconf). As such, the license of aimake does not restrict what licenses and distribution terms you use for programs that you compile with aimake.
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
<program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<http://www.gnu.org/licenses/>.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
<http://www.gnu.org/philosophy/why-not-lgpl.html>.