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 properties of mymod, the source files, and a module someothermode 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.

Run make from the direectory containing your build description file. Variables can be set from the command line using VAR=value, and specific modules can be specified as targets.

Example ::

make TS_REFCHECK=1 mymod

runs a refcheck (see below) build on the mymod modules.

TypeScript modules are added to the TSLIB variable. Each module can define the following variables:

• <modname>_src

  (required) A list of source files to build

• <modname>_deps

  (optional) A list of dependent modules

• <modname>_nodecls

  (optional) Set to 1 if declarations should not be created for this module.

Global variables that control the building of TypeScript modules include:

• TSLIBS

  (required) The list of TypeScript modules to build

• TS_SRC_DIR

  (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.

• TS_REFCHECK

  (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 _nodecls variable has been set).

If neither TS_MODULAR or 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_MODULAR or TS_REFCHECK appropriately in your Makefile to enable a different mode by default.

Below are some advanced / internal variables. All optional.

• TS_OUTPUT_DIR

  Controls the destination of build output. By default this is one of jslib, jslib-modular, jslib-refcheck based on the build mode, but it can be overriden.

• _<mod>_out_js

  Overrides the destination file for the given module. Used only when TS_MODULAR is set.

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 depend on 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 ::

path/to/extmod/lib/libext.a

C++ modules are added to one of LIBS (static lib), DLLS (dynamic lbi) or APPS (applications). Each module may define:

• <modname>_src

  (required) List of .cpp or .c files to compile

• <modname>_incdirs

  Any include paths used in compiling this module. Include paths will also be used in compiling any module that depends on <modname>.

• <modname>_deps

  C++ modules on which <modname> depends.

• <modname>_extlibs

  External libs on which <modname> depends (see 'External Libraries' above).

• <modname>_unity

  If set to 1, attempt to compile all source files in a single invocation of the compiler.

• <modname>_pch

  A header file to be used as a precompiled header for this module.

• <modname>_cxxflags

  Extra flags to pass to the compiler when building this module and any modules that depend upon it. Useful for flags such as -DENABLE_FEATURE=1.

• <modname>_local_cxxflags

  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 c to force a single module to be compiled as C instead of C++.

CONFIG

TARGET TARGETNAME BUILDHOST