Ubuntu Manpage: mymake - simple build system for C/C++

NAME

       mymake - simple build system for C/C++

SYNOPSIS

       mymake  [-?]  [-f]  [-c]  [-t]  [-e] [-ne] [-p path] [-j processes] [-o output] [-d level]
       [--default-input input] [files]... [options]... [-- args...]
       mymake --config
       mymake --target
       mymake --project

DESCRIPTION

The mymake program builds C/C++ programs. It aims to be able to build simple programs
(referred to as targets) with close to zero configuration, yet be powerful enough to
handle larger programs as the initially simple project grows.

Once installed, run

mymake --config

to generate the global configuration file for the current user. This file specifies how to
compile C/C++ programs on the current system, and defines the default parameters that can
be used in other files as described below. The default contents are typically sufficient.

After the initial configuration, a simple program can be compiled by navigating to the
directory the source code of the program and typing

mymake myprogram.cpp

This will compile and link the program using the configuration in the global
configuration, and if compilation is successful also execute the program. Command-line
parameters may be passed to the program using the -- or the -a parameter

mymake myprogram.cpp -- param1 param2...

The default behavior also works with programs consisting of multiple files. mymake
examines which files are included in the source file specified on the command-line and
compiles those files as well. This is based on the assumption that if the file utils.h is
included, then the file utils.cpp should also be compiled (if it exists). Of course,
different extensions than .cpp are also examined. As is typically the case with other
build systems, only files changed since the last build are rebuilt.

If the program being compiled does not follow the assumption that header files and
implementation files appear pairwise, it is possible to create a file called .mymake in
the project directory and add the following to it

[]
input=*

This instructs mymake to include all implementation files in the compilation, regardless
of whether or not they are considered to be needed by the program or not. It is also
possible to add a particular file to the input statement (e.g. myprogram.cpp). In both
cases, it will no longer be necessary to specify a file on the command line.

As of version 2.3.0, mymake tracks the command-lines used to compile each file, and re-
compiles source files where the command line has changed. This means that mymake is able
to re-compile the relevant parts of the project if the configuration file has changed.

As the project grows, it is also possible to divide the project into separate sub-projects
and have mymake manage dependencies automatically. This is done by creating a .myproject
file in the root directory of the project. This tells mymake to treat all directories as
sub-projects, each which may contain their own .mymake file. See CONFIGURATION for
details.

OPTIONS

The usual GNU command line syntax is respected, with long options starting with two dashes
(`-'). Long options are equivalent to short options.

-?, --help
Print a message outlining basic usage and command-line options.

-f, --force
Force re-compilation of all required files, even files that would otherwise be
considered to be up-to-date. This is useful if the configuration files were
changed, for example.

-c, --clean
Clean build files by removing the execDir and buildDir indicated by the
configuration based on any options specified.

-t, --time
Output information about the wall-clock time used in each step of compilation.

-e, --execute
Execute the executable after successfully building a target. The default
configuration executes the program, but this behavior may be overridden by project-
specific configuration files. The command-line parameters overrides all
configuration files.

-ne, --not --execute
Do not execute the executable after a successful build. The inverse of -f.

-p, --exec-path
Specify the working directory when running the compiled executable. The default
value is the path of the project to which the executable belongs.

-j processes, --threads processes
Spawn up to the specified number of processes in parallel during compilation. This
typically means that compilation may use up to the specified number of hardware
threads. This is typically not needed, as the user's preference is specified in the
global configuration file.

-o output, --output output
Specify the name of the output file (note: not the location). This can be used to
override the default behavior, but this is better done in one of the configuration
files.

-d level, --debug level
Specify the debug level, either as a number or as the associated label. The
following levels are available:

0: QUIET
No output except for fatal errors.

1: NORMAL
The default value. Outputs progress information.

2: PEDANTIC
Warns about configuration issues that might be errors. Useful as a first
step in debugging configurations.

3: INFO
Prints information about decisions during the build. Good for debugging
configurations.

4: VERBOSE
All information you will typically need when debugging configuration issues.

5: DEBUG
Information typically only needed when debugging mymake itself.

--default-input input
Add input as an input file if no other inputs were specified either on the command
line or in any configuration files. This option is intended to be used when
integrating mymake in an editor. The editor may then always supply the name of the
current open file as a --default-input to make mymake do the right thing based on
configurations: compiling the current file if nothing else is specified, otherwise
follow the other, more precise instructions in the configuration files.

[options]
Zero or more options may also be specified on the command line. These options may
correspond to sections in one of the configuration files to enable (or disable).
See the CONFIGURATION section below for details.

[files]
Files may also be specified on the command line. Mymake will add all names that
correspond to existing files (possibly first appending known file extensions) to
the list of input files to process.

--config
Create the global configuration in ~/.mymake. This can also be used to revert the
global configuration to the default state. Will ask for the preferred number of
threads to use during compilation.

--target
Creates the file .mymake in the current directory. It fills the file with a
template configuration that contains common options and settings.

--project
Creates the file .myproject in the current directory. The file contains a template
suitable for a project, i.e. a directory consisting of multiple targets.

CONFIGURATION

The configuration in mymake consists of a set of named variables, each of which contain an
array of strings. The value of these variables may originate from one (or more) of four
locations: the global configuration (~/.mymake), the project configuration (.myproject, if
present), the target configuration (.mymake, if present), or the command-line. The project
and target configurations may reside in the current directory, or any parent directories.
If a project configuration is found, target configurations are expected to be located in
sub-directories to the project configuration. Options are always applied in the order
specified above. This means that options in the global configuration may be overridden by
other configurations, and that the command-line parameters are always applied last. The
exception is when compiling a project. Then, command line parameters are only applied when
resolving the project configuration, not when resolving the configuration for individual
targets.

All configuration files follow the same format. They all consist of a sequence of
assignments to variables, optionally grouped into zero or more sections. Lines starting
with `#' are comments. Assignments have one of the following two forms:

name=value
name+=value

The first form replaces the entire contents of the variable with the string value, while
the second adds value as the last element of the array. As a special case, if the first
form is used, and value is empty, the variable is assigned the empty array. Assignments
may be grouped into sections by adding section headers before them. A section header has
the following form:

[option1,option2,...]

The meaning of the section header is: only consider the following assignments if all
options that appear in the header are present in the context in which the configuration is
evaluated (e.g. specified on the command line). Thus, the header [] is always evaluated,
[release] is only evaluated if the release option has been specified, and [release,unix]
only if both release and unix have been specified. Additionally, an option may be prefixed
with an `!' to mean that the particular option has to be absent, for example:
[!release,unix].

Each configuration file is then evaluated by mymake in turn to provide the set of
variables to use during compilation. This is done by evaluating each assignment in each
file in the order they are specified, ignoring any sections that should be skipped
according to the available options. Typically, each file is only evaluated once, with a
context consisting of the options specified on the command-line. The exception is
.myproject-files, which are covered in the PROJECTS section below.

PRE-DEFINED OPTIONS

       The following options are pre-defined by mymake or the default configuration, and  can  be
       used by default:

       release
              Produce  a  release  version  of  the program. This typically means turning on more
              aggressive optimizations.

       lib    Produces a static library. Typically used in projects when some targets are  static
              libraries used by other targets in the project.

       sharedlibe
              Produces a dynamic library. Typically used in projects, like lib.

       unix   Defined by mymake when compiling for a UNIX-like system.

       windows
              Defined by mymake when compiling for a Windows-like system.

       project
              Defined automatically when evaluating the .myproject file in the project context.

       build  Defined  automatically  when evaluating the .myproject file to find options for the
              targets in a project.

       deps   Defined  automatically  when  evaluating  the  .myproject  file  to  find  explicit
              dependencies between projects.

VARIABLES

The following variables are used by mymake to define what should be done. Some of these
variables are treated specially by mymake itself, others are just defined by the global
configuration. It is possible to define and use other variables in configuration files.

ext Array of the file extensions you want to compile. Whenever mymake realizes you have
included x.h, looks for all extensions in ext and tries them to find the
corresponding implementation file.

execExt
File extension of executable files. Added to the output filename automatically.

intermediateExt
File extension of intermediate files. Typically .o on UNIX systems.

buildDir
String containing the directory used to store all temporary files when building
your program. Relative to the root directory of the target (i.e. where the .mymake
file is).

execDir
String containing the directory used to store the final output (the executable) of
all targets. Relative to the root directory of the target.

ignore Array of wildcard patterns (like in the shell) that determines if a certain file
should be ignored. Useful when working with templates sometimes, or when parts of
the source code should not be compiled.

noIncludes
Array of wildcard patterns (like in the shell) that determines if a certain path
should not be scanned for headers. Useful when you want to parts of the code that
is not C/C++, where it is not meaningful to look for #include.

input Array of file names to use as roots when looking for files that needs to be
compiled. Anything that is not an option that is specified on the command line is
appended to this variable. The special value * can be used to indicate that all
files with an extension in the ext variable should be compiled. This is usually
what you want when you are compiling a library of some kind.

output String specifying the name of the output file. If not specified, the name of the
first input file is used instead.

appendExt
Append the original extension of the original source file to the intermediate file
when compiling. This allows mymake to compile projects where there are multiple
files with the same name, e.g. foo.cpp and foo.c without both trying to create
foo.o and thereby causing compilation to fail. Mymake warns you if you might need
to add use this option.

include
Array of paths that should be added to the include path of the compilation.

includeCl
Flag to prepend all elements in include.

includes
Generated automatically by mymake, equivalent to adding the contents of includeCl
before each element in include.

library
Array of system libraries that should be linked to your executable.

libraryCl
Flag to prepend all elements in library.

localLibrary
Array of local libraries that should be linked to your executable (usually used in
a project).

localLibraryCl
Flag to prepend all elements in localLibrary.

libs Automatically generated by mymake, equivalent to adding libraryCl before all
elements of library, also including local libraries.

define Preprocessor defines.

defineCl
Preprocessor define flag.

exceute
Yes or no, telling if mymake should execute the program after a successful
compilation. This can be overridden on the command line using -e or -ne.

pch The precompiled header file name that should be used. If you are using the default
configuration, you only need to set this variable to use precompiled headers. If
you are using #pragma once in gcc, you will sadly get a warning that seems
impossible to disable (it is not a problem when precompiling headers).

pchFile
The name of the compiled version of the file in pch.

pchCompile
Command line for compiling the precompiled header file.

pchCompileCombined
If set to yes, pchCompile is expected to generate both the pch-file and compile a
.cpp-file.

preBuild
Array of command-lines that should be executed before the build is started. Expands
variables.

preBuildCreates
Array of files created by the pre-build step which should also be included in the
compilation. These are expected not to introduce any additional dependencies into
the project, as they are not available at the point where mymake resolves
dependencies between files and targets.

postBuild
Array of command-lines that should be executed after the build is completed.
Expands variables.

compile
Array of command lines to use when compiling files. Each command line starts with a
pattern (ending in :) that is matched against the file name to be compiled. The
command line added last is checked first, and the first matching command-line is
used. Therefore it is useful to first add the general command-line (starting with
*:), and then add more specific ones. Here, you can use <file> for the input file
and <output>.

link Command line used when linking the intermediate files. Use <files> for all input
files and <output> for the output file-name.

linkOutput
Link the output of one target to any target that are dependent on that target. See
projects for more information.

forwardDeps
Forward any of this target's dependencies to any target that is dependent on this
target.

env Set environment variables. Each of the elements in env are expected to be of the
form: variable=value or variable<=value or variable=>value. The first form replaces
the environment variable variable with value, the second form prepends value to
variable using the system's separator (: on unix and ; on windows), the third form
appends value to variable. The second and third forms are convenient when working
with PATH for example.

explicitTargets
In projects: ignore any potential targets that do not have their own .mymake-file.

parallel
In projects, this indicates if projects that have all dependencies satisfied may be
built in parallel. The default value is yes, so projects not tolerating parallel
builds may set it to no. In targets, this indicates if files in targets may be
built in parallel. If so, all input files, except precompiled headers, are built in
parallel using up to maxThreads threads globally. If specific targets do not
tolerate this, set parallel to no, and mymake will build those targets in serial.

maxThreads
Limits the global number of threads (actually processes) used to build the
project/target globally.

usePrefix
When building in parallel, add a prefix to the output corresponding to different
targets. Defaults to either vc or gnu (depending on your system). If you set it to
no, no prefix is added. vc adds n> before output, gnu adds pn: before output. This
is so that Emacs recognizes the error messages from the vc and the gnu compiler,
respectively.

absolutePath
Send absolute paths to the compiler, this helps emacs find proper source files in
projects with multiple targets.

implicitDeps
(defaults to yes), if set, mymake tries to figure out dependencies between targets
by looking at includes. Sometimes, this results in unneeded circular dependencies,
causing compilation to fail, so sometimes it is neccessary to set this to no.

All variables that contain commands to execute can be prefixed with an integer followed by
a colon (for example 1:gcc). If prefixed with the integer N, the first N lines of output
from that command are removed from the output. As such, this can be used to ignore status
information from commands during the build, without ignoring useful information. For
example, the C++ compiler on Windows outputs a line containing the filename being compiled
by default. This is unnecessary as mymake already does this. It can thus be suppressed by
issuing the command 1:cl ....

This feature is possible to use in the variables compile, pchCompile, and link.

VARIABLES IN STRINGS

When mymake uses some variables (most notably, the compilation and link command lines) it
looks at each string and recursively replaces any variables that appear there. Note that
this is not done when the configuration is evaluated, only when the variables are actually
used.

Any occurrences of <variable> are replaced with the contents of variable. It is also
possible to prepend a string to each element in another variable using the syntax
<prefix*variable>, which means that the string in the variable prefix is prepended to each
element in the variable variable.

The special variable <env:X> (where X is any string) can be used to extract the value of
environment variables. This is useful to, for example, inspect the value of CFLAGS during
compilation. The benefit of using this syntax over relying on shell expansion is that it
allows mymake to track changes in the environment variables.

It is also possible to perform an operation on each element in the array using the syntax
<op|variable>. It is also possible to both perform an operation and prepend data using
<prefix*op|variable>. Supported operations are:

title Treat the element as a path and extract the file or directory name (e.g.
src/foo.txt gives foo.txt).

titleNoExt
Same as title, but the file extension is removed as well.

noExt Remove the file extension from a path.

path Format the element as a path for the current operating system. For example
src/foo.txt evaluates to src\foo.txt on Windows.

buildpath
Make the element into a path inside the build path.

execpath
Make the element into a path inside the executable path.

parent Evaluates to the parent directory of the path. If no parent is given (e.g. only a
file name), the element is removed from the array.

if Make all elements empty. This can be used to test if a variable contains a value
and then include some other text. For example <usePch*if|pchFile> to add the flag
inside usePch if a file is specified in pchFile.

PROJECTS

A project is a collection of targets linked together by a .myproject-file. The .myproject
file is evaluated multiple times with different options present to extract information
about the project:

build: This option is specified during one evaluation to extract a list of options to
apply to each of the sub-projects. Thus, a project file typically contains a section as
follows:

[build]
main+=debug
libfoo+=lib
libfoo+=debug

In this case, we instruct mymake to build the main target with the debug option present,
and the target libfoo with the options debug and lib. There is also a special target, all,
which options will apply to all targets in the project.

deps: This option is specified during one evaluation to extract explicit dependencies
between projects. By default, mymake finds dependences between projects automatically by
examining includes across projects. In certain cases it is, however, useful to introduce
extra dependencies to ensure that some dynamically loaded parts are also built. This
section is very similar to the build section. Mymake expects to find variables
corresponding to each target, and that these variables contains names of other targets.

If one target results in a library, it is convenient to set the variable linkOutput to yes
for that target. Mymake will then add the output of the library target to the library
variable of any targets that depend on it.

After mymake has extracted the necessary project information, the .myproject-file is also
evaluated once for each target. Thus, it is possible to specify additional variables or
options that apply to all targets in the project in the .myproject file.

June 22 2021 MYMAKE(1)