Builder
-Copyright © 2006-2012 Mikkosoft Productions
-Version 2.0 readme
+Copyright © 2006-2022 Mikkosoft Productions
+Version 3.0 readme
-------------------------------------------------------------------------------
1. Description
2. Building Builder
3. Using Builder
-4. Command line options
-5. Architectures and cross-compilation
-6. Dependency analysis
-7. Writing Build files
-8. Contact information
-9. License
+4. Locating packages
+5. Command line options
+6. Virtual targets
+7. Tarballs
+8. Architectures and cross-compilation
+9. Dependency analysis
+10. Logging
+11. Writing Build files
+12. Contact information
+13. License
-------------------------------------------------------------------------------
2. Building Builder
-Builder is normally built using itself. However, if you just downloaded the
-source and don't yet have a Builder binary, how is that possible? To resolve
-this problem, there's a script called bootstrap.sh in the Builder main
-directory. Before running it, make sure you have the following libraries
-available:
+Builder is normally built using itself. This creates a conundrum if you just
+downloaded the source and don't yet have a Builder binary. To resolve the
+problem, there's a script called bootstrap.sh in the Builder main directory.
+Before running it, make sure you have the following libraries available:
-MSP libraries: core datafile
+MSP libraries: core crypto datafile
Others: sigc++-2.0
-Since the MSP libraries are also normally built with Builder, the script will
-need to have their sources available. By default, it will look at the parent
-directory of builder. You can change this by setting the LIBPATH evironment
-variable for the script. If everything goes well, the script will build a
+You should be able to get the MSP libraries from the same place you got
+Builder itself from. Since they are also normally built with Builder, the
+script will need to have their sources available. By default, it will look at
+the parent directory of builder. You can change this with the --libpath
+parameter for the script. If everything goes well, the script will build a
builder-stage1 binary and then proceed to build a normal version with it.
-------------------------------------------------------------------------------
what to build by default.
While loading the package, other packages may be pulled in through require
-statements. Builder tries to locate the source for each required package by
-consulting pkg-config and looking through its package path. If the source
-can't be found, a binary package is tried next, from pkg-config and Builder's
-internal package database. If the package still can't be found, the build
-will fail. Loading external source packages can be disabled with the -x
-option.
+statements. Refer to section 4 for how packages are located. A package that
+can't be found will cause the build to fail. If the -x option was specified,
+builder will only consider binary packages when looking for dependencies.
When building, the primary targets of each package are placed in the package's
root directory. To build a subset of targets from the package, the desired
targets can be named on the command line. Paths are interpreted relative to
Builder's working directory. The analyzer can be useful in finding out what
-targets are available; see section 6 for details.
+targets are available; see section 9 for details.
To configure optional package features, arguments of the form key=value may be
given. To obtain a list of available features, use the --help option in the
-------------------------------------------------------------------------------
-4. Command line options
+4. Locating packages
+
+Most packages are not self-contained, but depend on other packages. When such
+dependencies are encountered, the packages need to be located. This section
+describes the various places Builder looks for them from.
+
+First, Builder asks pkg-config if it knows the location of the source
+directory of the package. This is stored in the source variable in the .pc
+file, and is automatically put there by Builder. If the variable is found,
+Builder further verifies that it refers to an existing directory which
+contains a Build file, so that removed sources do not cause undue failures.
+
+If pkg-config does not know about the source, Builder consults its own package
+path. Currently this is hardcoded to contain the main package's source
+directory and its parent directory. To be found this way, the directory
+should be named the same as the package, optionally followed by a dash and a
+version number (or really anything; the part after the last dash is ignored).
+
+If the source can't be found at all, Builder will then turn to using a binary
+package. Builder's native packages are considered first. They are normally
+stored in <prefix>/share/builder with the extension bpk. The base part of the
+filename should be the as the package's name.
+
+Finally, pkg-config is consulted for the build flags of the package in the
+normal way. The flags need to be translated to Builder's internal
+representation, so if the package requires very unusual flags, it may not
+work.
+
+A package that can't be found after all these steps might as well not exist.
+
+-------------------------------------------------------------------------------
+
+5. Command line options
When both Builder and GNU make offer the same functionality, the command line
option to invoke it is the same as well.
-a, --analyze MODE
- Perform dependency analysis. See section 6 for details.
+ Perform dependency analysis. See section 9 for details.
-b, --build
Perform a build. This is the default action. This option can be used to
far in excess of the amount of logical CPU cores in the system.
-l, --log LIST
- Enable output from a comma-separated list of log channels.
+ Enable output from a comma-separated list of log channels. This is mainly
+ useful for debugging Builder itself; for normal use the -v option is almost
+ always enough. Refer to section 10 for the available log channels.
-n, --dry-run
Show what would be done without actually doing it. This is useful in
--arch ARCH
Build for architecture ARCH. If the architecture is not native, this will
- result in cross-compilation. See section 5 for details.
+ result in cross-compilation. See section 8 for details.
--conf-only
Stop after configuring packages. This can be useful if you want to
useful. The default is 4.
--prefix DIR
- Install things to DIR. The default is $HOME/local.
+ Install files to DIR. The default is $HOME/local.
--tempdir DIR
Store temporary files in DIR. If a relative path is specified, each package
-------------------------------------------------------------------------------
-5. Architectures and cross-compilation
+6. Virtual targets
+
+Builder provides virtual targets for certain tasks, as well as for internal
+organization of the build graph. They can appear on the command line along
+with file-based targets.
+
+world
+ Depends on everything that can be built.
+
+default
+ Depends on the targets that are built by default. If no targets are
+ specified on the command line, then this target will be built.
+
+install
+ Depends on all installed files. This also includes .pc files, which are
+ otherwise not normally built.
+
+tarballs
+ Depends on source tarballs of all packages.
+
+goals
+ Depends on all targets on the command line. Trying to add this target to the
+ command line will cause Builder to abort due to a circular dependency.
+
+-------------------------------------------------------------------------------
+
+7. Tarballs
+
+Since the source tree usually contains files that do not belong to a release
+archive, be they version control metadata or temporary build files, Builder
+provides a way to create a clean source tarball for a package. It will
+contain all non-buildable files belonging to the package, including its Build
+file.
+
+Source tarballs are named as <package>-<version>.tar. Currently compression
+is not supported.
+
+-------------------------------------------------------------------------------
+
+8. Architectures and cross-compilation
If the necessary compilers and other tools are available, Builder can cross-
compile binaries for other systems. To activate cross-compilation, use the
-------------------------------------------------------------------------------
-6. Dependency analysis
+9. Dependency analysis
Builder can perform a dependency analysis in various ways. This can provide
useful insight to the relations between targets. It may also be helpful if
-------------------------------------------------------------------------------
-7. Writing Build files
+10. Logging
+
+Sometimes you need to figure out what Builder is doing, perhaps because it's
+doing it wrong or you're just curious. To this end, a number of logging
+channels are provided. To specify which channels to enable, use the -l
+option. Some channels are also turned on by the -v option; the default
+verbosity level is 1. The -s option disables all channels.
+
+auxcommands
+ Prints commands that are not directly related to building targets, such as
+ pkg-config invocations. Enabled at verbosity level 3.
+
+cache
+ Displays cached values as they are loaded. Generates a lot of spam.
+
+commands
+ Prints commands used for building targets. Internal commands will print
+ "<internal>". Enabled at verbosity level 2.
+
+configure
+ Shows conditionals encountered in package Build files and whether they
+ matched.
+
+environment
+ Displays overall parameters used in the build. Enabled at verbosity level 2.
+
+files
+ Indicates files that are being read or written, as well as directory scans.
+ Enabled at verbosity level 3.
+
+packagemgr
+ Shows what's being done to locate packages.
+
+packages
+ Displays a list of active packages at startup, together with their target
+ counts if they are source packages. Enabled at verbosity level 2.
+
+rebuild
+ Shows why targets are being rebuilt. Similar to -a rebuild.
+
+summary
+ Displays a brief summary of what will be done. Enabled by default.
+
+tasks
+ Displays abstract descriptions of what is being done. Enabled by default.
+
+tools
+ Displays information related to tools, such as versions.
+
+vfs
+ Shows what files are being looked for and where. Generates a lot of spam.
+
+-------------------------------------------------------------------------------
+
+11. Writing Build files
Before going into details about Builder instruction files, it's beneficial to
understand the basic concepts used in Builder. There are three kinds of major
require "otherlib";
-pkg-config is used to locate dependencies, and failing that, some heuristics
-are applied to find Builder-enabled packages.
+See section 4 for how packages are located.
To be useful, a package must define one or more components. At present, there
are four types:
automatically determined from the component type. Library components will also
install any headers which were used to build the library.
+Components can have requirements, just like packages. They can also use
+library components from the same package:
+
+ use "mylib_common";
+
+This can be useful in organizing code when multiple components in a package
+share a common part. If the used library is not specified to be installed,
+it will be linked statically.
+
Packages may want to offer optional features, for example to allow the user to
choose whether to use a particular external library:
};
Any statements inside the conditional block are evaluated if the feature is
-enabled. This can be negated with a !. Conditionals can appear at the package
-level and may contain anything that the package statement can.
+enabled. This can be negated with a !. Conditionals can appear at package and
+component scopes and may contain anything that the enclosing statement can.
When making cross-platform software, it's often necessary to use different
libraries on different platforms. Another kind of conditional can be used for
...
};
-See section 5 for more information on how to specify an architecture. The
+See section 8 for more information on how to specify an architecture. The
conditional block is evaluated if all parts in the condition match the target
architecture.
recommended to use absolute paths, as this can make your package difficult to
build for others.
+To include additional files in the package's source tarball, such as
+documentation, use the source_tarball statement. It takes no argument, as the
+name is generated internally, but otherwise it behaves as a tarball component.
+
For real-life examples, see the Build files in Builder itself or any of the
MSP libraries.
-------------------------------------------------------------------------------
-8. Contact information
+12. Contact information
The latest releases can be found at http://www.tdb.fi/builder.shtml
Bug reports, feature requests etc. may be sent to tdb@tdb.fi
-Read-only git access is available at http://git.tdb.fi/builder
+Read-only git access is available at git://git.tdb.fi/builder
-------------------------------------------------------------------------------
-9. License
+13. License
-Builder is copyright © 2006-2012 Mikko Rasa, Mikkosoft Productions
+Builder is copyright © 2006-2022 Mikko Rasa, Mikkosoft Productions
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
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
Full license text can be found in License.txt.
-
-
-7. Version history
-
-0.9
-- First released version
projects / builder.git / blobdiff