Table of Contents
The build process of a source package is controlled by several logic scripts. A logic file defines targets and associates several types to them (which in turn means that actions are added to the default stages).
A single entity within your source tree that needs to be handled during the build of the package. It will usually have target files associated to it, hence the name.
Something that can be done on targets. The standard stages are build, clean, cleandir, deinstall, install and test. What they do, and how to invoke them, is explained in Chapter 5, Building targets.
Aside from build, all other stages are "phony" (in Make terminology), which means they do not produce files in the current directory and are always considred out of date.
Gives specific instructions on how to execute a stage on a given target. It relates both concepts.
bt_target target1 ... targetN
To tell bt_logic which targets are available in a script file, use the bt_target function. All arguments given to it are treated as new targets that will be built in the given order.
bt_target fooprogram foolibrary
The logic script in the top directory of your project will usually recurse into other directories (note, usually, but not always; bt_logic leaves you the freedom to do it another way).
This script can either be a top level Logic.bt file or be embedded into Generic.bt through the logic function (the later is highly recommended).
As a sample script, consider the following, which will automatically enter the `lib' and `src' directories, and associate all available stages to them:
logic() {
bt_target lib src
}
Inside this top level function, the following variables are honoured:
If set to no, do not install document files registered in the docs section with the bt_doc function.
Note that when entering any directory, if a Logic.bt file is found in it, bt_logic will use it instead of the top level one.
To define a target, declare the target_<name> function in your script. This function will only set variable values that affect the target. These variables are made local to the target, so they not affect other targets that may appear in the same file. (Variables made local are those listed in the BT_TARGET_DEFS and BT_TARGET_VARS lists).
Useful, common variables you can define:
List of targets to be executed as dependancies before the given stage is applied to this one.
Set to yes to disable the build stage in the current target.
Set to yes to disable the clean stage in the current target.
Set to yes to disable the cleandir stage in the current target.
Set to yes to disable the deinstall stage in the current target.
Set to yes to disable the install stage in the current target.
Set to yes to disable the test stage in the current target.
Enter a directory before building the target (but avoid reading any Logic.bt that may exist there).
A different name for the generated file. Defaults to target's name.
A different name for the target than the one given in the function name. You won't need this one, hopefully.
Assigns a type to the target. Defaults to the null type.
Other variables, related to C/C++ compilation: BT_FLAGS_CPP, BT_FLAGS_CC, BT_FLAGS_CXX, BT_FLAGS_LD, BT_LIBS (with their usual meaning).
You may define actions to be taken before and after a stage is executed. These are global and do not apply to specific targets, meaning that they will be always executed when invoking their respective stage on any target.
I.e.:
pre_build() {
echo "Hey! I'm starting to build this program!"
}
post_build() {
echo "Wow! Build finished!"
}
post_deinstall() {
echo "Didn't you like it? :'("
}
Similar to what said in Section 12.4, “Pre/post actions for stages”, you can define actions to be taken before and after an specific target is executed:
target_myprogram_post_build() {
echo "You know, myprogram has been built successfully!"
}
If there is a type that half-suits your target, you can override some of its stages with your preferred commands. I.e.:
target_myprogram() {
BT_TYPE=program
...
}
target_myprogram_build() {
echo "program's type build doesn't fit our needs... override it"
...
}
This lets you build executable programs. The following variables are recognized in the target definition:
If set to yes, this target is treated as a test program. What this means is that it will be run automatically during the test stage.
List of manual pages to be installed.
List of source files (either C or C++).
As an example:
target_fooprogram() {
BT_TYPE="program"
BT_SOURCES="file1.c file2.cpp"
BT_MANPAGES="foo.1 bar.6"
}
This lets you build static and shared libraries automatically, depending on what the configuration script detected; it also provides support for manual page installation. See the archive and shlib types for more information, as they are directly used by this one.
Some common variables:
List of header files to be installed.
Directory where header files listed in BT_INCLUDES are installed. Defaults to BT_DIR_INCLUDE (set by the configure script).
Directory where the specific header headername is installed (replace dots with underscores).
Whether to build a shared library or not. Automatically set by configure. Do not change.
whether to build a static library or not. Automatically set by configure. Do not change.
List of manual pages to be installed.
List of source files (either C or C++).
As an example:
target_foolibrary() {
BT_TYPE=library
BT_LIB_MAJOR=1
BT_LIB_MINOR=5
BT_LIB_MICRO=7
BT_SOURCES="lib1.c lib2.c"
}
This lets you build archive files, independantly on what the configuration script detected (that is, for convenience archives, for example).
Variables recognized:
List of source files (either C or C++).
This lets you build shared libraries and/or plugins, assuming they are supported in the current platform.
Variables recognized:
Major version specification for the library. May be left empty for plugins.
Minor version specification for the library. May be left empty for plugins.
Micro version specification for the library. May be left empty for plugins.
List of source files (either C or C++).
Target file name. Only use it in special situations (i.e., building a plugin).
This implements automatic conversion between file types (i.e., from .c source code to .o object files). This is used to automatically define targets when they are not explicitly provided by the user. Also used intensively in generated dependancy files (.dep).
Variables recognized:
Whitespace separated list of extensions to be automatically recognized. Similar to Make's .SUFFIXES directive but without the prefixing dot for each element.
Name of source file.
Suffix of source file.
Name of target file.
Suffix of target file.
To define a new conversion, for example from .html to .xml:
BT_CONVERT_SUFFIXES+="html xml"
convert_html_xml() {
# commands to issue the conversion during the build stage
}
This is similar to the convert type, but used to create files with the bt_output utility (generated from the configure script by the call to bt_generate_output; see Section 11.5.1, “Generating output files”). This type is automatically used by bt_logic when possible (i.e., a you are building a file that does not exist, but one with the same name with a trailing .in suffix does), so you should not care about defining your own targets.
For example, if you have the test.in file, you could do the following to get test automatically generated for you:
bt_target test
This is useful to handle generation of .info files and their installation on the system.
Variables recognized:
Filename of the source file. Must end in .texi.
This lets you build executable programs that use the QT library. Headers used to build these programs will usually need a converstion to .moc files. This type provides functionality to generate these files. The program itself is handled by the regular 'program' type later, so all variables that affect it are applicable here too.
Variables recognized:
List of .h headers that have to be converted to .moc before building the program.