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:
BT_INSTALL_DOCS
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:
BT_DEPENDS
List of targets to be executed as dependancies before the given stage is applied to this one.
BT_NO_BUILD
Set to yes to disable the build stage in the current target.
BT_NO_CLEAN
Set to yes to disable the clean stage in the current target.
BT_NO_CLEANDIR
Set to yes to disable the cleandir stage in the current target.
BT_NO_DEINSTALL
Set to yes to disable the deinstall stage in the current target.
BT_NO_INSTALL
Set to yes to disable the install stage in the current target.
BT_NO_TEST
Set to yes to disable the test stage in the current target.
BT_SUBDIR
Enter a directory before building the target (but avoid
reading any Logic.bt
that may exist
there).
BT_TARGET_FILE
A different name for the generated file. Defaults to target's name.
BT_TARGET_NAME
A different name for the target than the one given in the function name. You won't need this one, hopefully.
BT_TYPE
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:
BT_IS_TEST
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.
BT_MANPAGES
List of manual pages to be installed.
BT_SOURCES
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:
BT_INCLUDES
List of header files to be installed.
BT_INCLUDESDIR
Directory where header files listed in
BT_INCLUDES
are installed. Defaults to
BT_DIR_INCLUDE
(set by the configure
script).
BT_INCLUDESDIR_<headername>
Directory where the specific header
headername
is installed (replace dots with
underscores).
BT_LIB_MKPIC
Whether to build a shared library or not. Automatically set by configure. Do not change.
BT_LIB_MKSTATIC
whether to build a static library or not. Automatically set by configure. Do not change.
BT_MANPAGES
List of manual pages to be installed.
BT_SOURCES
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:
BT_SOURCES
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:
BT_LIB_MAJOR
Major version specification for the library. May be left empty for plugins.
BT_LIB_MINOR
Minor version specification for the library. May be left empty for plugins.
BT_LIB_MICRO
Micro version specification for the library. May be left empty for plugins.
BT_SOURCES
List of source files (either C or C++).
BT_TARGET_FILE
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:
BT_CONVERT_SUFFIXES
Whitespace separated list of extensions to be
automatically recognized. Similar to Make's .SUFFIXES
directive but without the prefixing dot for each element.
BT_FROM_NAME
Name of source file.
BT_FROM_SUFFIX
Suffix of source file.
BT_TO_NAME
Name of target file.
BT_TO_SUFFIX
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:
BT_SOURCE
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:
QT_HEADERS
List of .h
headers that have to be
converted to .moc
before building
the program.