A build description file uses Make syntax. It is usually called
Makefile and typically takes the form ::
BUILDDIR := tzbuild # Path to the tzbuild directory include $(BUILDDIR)/config.mk # ... # Module declarations # ... include $(BUILDDIR)/rules.mk
The header sets the BUILDDIR variable to point to the root of tzbuild (required), and calls config.mk, which sets up several variables related to the build environment. Module declarations are then made, which describe the modules to be built and dependencies between them. Finally, rules.mk is called, which generates all build rules based on the module delcarations.
A more complete
Makefile example, including 'external' modules and
conditionals is given below. This should be a sufficient template for
most build requirements ::
BUILDDIR := build/tzbuild # (OPTIONAL) location of scripts that extend the build # functionality. Support for extra platforms can be added by # placing a file names `platform_<target>.mk` in this directory. CUSTOMSCRIPTS := build/scripts # (OPTIONAL) first step in the tzbuild configuration process. # This detects the build host and sets up some target variables # given the command line parameters. If not explicitly included, # it will be included by `config.mk`, but can be specified here to # allow the caller to make per-platform or external module # settings. include $(BUILDDIR)/config_platform_info.mk # (OPTIONAL) custom configuration values that will be picked up by # `config.mk`. COMPILER_linux64 ?= clang XCODE_SDK_VER := 10.12 # (OPTIONAL) 'external' modules (binary dependencies) should have # their names and versions specified here. The per-platform # values will be resolved by `config.mk`. curl_version := 7.48.0 curl_version_android := 7.27.0 curl_version_macosx := 7.33.0-tblz EXT += curl ifeq (debug,$(CONFIG)) EXT += testlib endif # (REQUIRED) remaining tzbuild configuration setup include $(BUILDDIR)/config.mk # (OPTIONAL) all other build configuration variables have now been # given default values and can be modified here before build rules # are generated. VARIANT:=-$(COMPILER)-$(GRAPHICS_DRIVER) UNITY ?= 1 CXXFLAGSPRE += -DMY_DEFINE ifeq (win,$(TARGETNAME)) CXXFLAGSPRE += -DIS_WINDOWS=1 endif # (OPTIONAL) external paths CURLDIR := $(external_path)/curl/$(curl_version) curl_incdirs := $(CURLDIR)/include $(CURLDIR)/include/$(EXTTARGET) curl_libfile := $(CURLDIR)/lib/$(EXTTARGET)/libcurl$(libsuffix) # (OPTIONAL) module definitions mylib_src := $(wildcard mylib/*.cpp) mylib/$(TARGETNAME)/platform.cpp mylib_incdirs := mylib LIBS += mylib myapp_src := $(wildcard myapp/*.cpp) myapp_deps := mylib APPS += myapp # (REQUIRED) build rules include $(BUILDDIR)/rules.mk
Modules are just a set of variables describing properties such as the location of source code, or depedent modules. Below is an example of a TypeScript module declaration ::
mymod_src := mymod/file1.ts mymod/file2.ts mymod_deps := someothermod TSLIBS += mymod
The last line here adds the name of the module
mymod to the special
variable TSLIBS. The system will later check this variable to find
the complete list of modules to build. Here we have defined just two
mymod, the source files, and a module
on which it depends. Given this name, tzbuild will check for
variables of the appropriate name, for example
mymod_src, etc. to
find source files.
Dependencies result in different behavior depending on the module types (and in some cases build configuration), but the intention is that the user only needs to specify dependencies between modules, and tzbuild will calculate all include paths, linked libraries (in the case of C++) and other build related parameters. For TypeScript modules, the system ensures that declarations for dependent modules are available, and generates the appropriate commandlines to include them.
There should be no need to specify this information by hand, and it should be automatically applied to all build configurations. This is in stark contrast to 'project' based systems, where the user must often specify project dependencies, include paths to dependencies and library files to link against by hand, often for each build configuration.
make from the direectory containing your build description file.
Variables can be set from the command line using
specific modules can be specified as targets.
make TS_REFCHECK=1 mymod
runs a refcheck (see below) build on the
TypeScript modules are added to the
TSLIB variable. Each module can
define the following variables:
(required) A list of source files to build
(optional) A list of dependent modules
(optional) Set to 1 if declarations should not be created for this module.
Global variables that control the building of TypeScript modules include:
(required) The list of TypeScript modules to build
(required for non-modular builds) The base directory of all source files. This is required when buildling TS files one-to-one into a destination directory so that the system can reconstruct the layout of source and destination files.
(optional) Set to 1 to enable reference checking. This ensures that all reference statements in the code are in order. Note that references are not a requirement of tzbuild, since tzbuild can calculate all dependencies from the module declarations. Some IDEs require that references be inserted into the code, and this mode can be used to ensure that references are correct.
TS_MODULAR(1 by default)
(optional) Set to 1 to enable a modular build. This uses the dependencies described in the module declarations to build each module into a .js file. All modules are expected to compile with no type errors, and a .d.ts declaration file is also generated (unless the
_nodeclsvariable has been set).
TS_REFCHECK are set to
1, the build
turns each .ts file into a .js file in the destination directory, and
does NO type checking. This is intended for people migrating to
typescript who wish to introduce a build and enable type checking
later. Modular and refcheck builds inist that code is type-correct.
By default, modular builds are performed. Set
TS_REFCHECK appropriately in your Makefile to enable a different
mode by default.
Below are some advanced / internal variables. All optional.
Controls the destination of build output. By default this is one of
jslib-refcheckbased on the build mode, but it can be overriden.
Overrides the destination file for the given module. Used only when
Used to reference pre built static or dynamic libraries. Usually take one of 2 forms ::
extmod_incdirs := path/to/extmod/include extmod_libdir := path/to/extmod/lib extmod_lib := ext EXT += extmod
where the include path is used in compiling any local modules that
extmod, and any apps or dlls with a dependency are
linked using ::
-L $(extmod_libdir) -l $(extmod_lib)
Alternatively, the path to the lib file can be given ::
extmod_incdirs := path/to/extmod/include extmod_libfile := path/to/extmod/lib/libext.a EXT += extlib
in which case, link commands of dependent modules use the form ::
C++ modules are added to one of
LIBS (static lib),
APPS (applications). Each module may define:
(required) List of .cpp or .c files to compile
Any include paths used in compiling this module. Include paths will also be used in compiling any module that depends on
C++ modules on which
External libs on which
<modname>depends (see 'External Libraries' above).
If set to
1, attempt to compile all source files in a single invocation of the compiler.
A header file to be used as a precompiled header for this module.
Extra flags to pass to the compiler when building this module and any modules that depend upon it. Useful for flags such as
Extra flags to pass to the compiler when building this module only. Modules that depend upon this module do not see these flags. Useful for flags such as
-x cto force a single module to be compiled as C instead of C++.