bmk.bbdoc

+BMK

BMK is a command line tool that drives the BlitzMax compiler and provides other general 'housekeeping' operations.

The general syntax for  BMK is:
{
@bmk %Operation %Options %Arguments
}

Where operation is one of @makeapp, @makemods, @zapmod, @unzapmod.

+@Makeapp

Makeapp builds an application from a single <i>root</i> source file. Building an application involves compiling source files and linking together the resultant %object files.

Makeapp takes one argument: the root source file to be built.

The root source file is scanned by BMK for #Import, #Include and #Incbin statements, and these files are themselves automatically built as well.

Unless the -a option is used, only source files that have been modified since the last makeapp operation are recompiled. This can vastly improve compile times.

Valid options for makeapp are:
[ @Option | @Effect
* @{-a} | Recompile all source files regardless of timestamp. By default, only files modified since the last makeapp are recompiled.
* @{-b <custom appstub module>} | Builds an app using a custom appstub (i.e. not BRL.Appstub). This can be useful when you want more control over low-level application state.
* @{-d} | Build debug version. This is the default.
* @{-g <architecture>} | Compiles to the specified architecture. (the default is the native for this binary - x86) Options vary depending on the current OS, architecture and installed toolchain. MacOS: x86, x64. Win32: x86, x64. Linux: x86, x64. iOS: x86, x64 (simulator), armv7, arm64. Android: x86, x64, arm, armeabi, armeabiv7a, arm64v8a. RaspberryPi: arm. Emscripten: js.
* @{-h} | Build multithreaded version. By default, the single threaded version is built.
* @{-i} | Creates a Universal build for MacOS or iOS. For MacOS, it will create an x86/x64 universal app. For iOS, it will create an armv7/arm64 universal app. If you want to profile your iOS apps, you need to use this option.
* @{-l <target platform>} | Cross-compiles to the specific target platform. Valid targets are win32, linux, macos, ios, android, raspberrypi and emscripten.
* @{-o} %OutputFile | Specify output file. By default, the output file is placed into the same directory as the root source file.
* @{-q} | quiet build
* @{-quick} | skips searching for modules it has to recompile. Without "-quick" all modules used by the programme are checked for changes. 
* @{-r} | Build release version. By default, the debug version is built.
* @{-t} %AppType | Specify application type. Should be either 'console' 
or 'gui' (without single quote!). Default is console.
* @{-v} | verbose (noisy build)
* @{-x} | Execute built application
]

Some examples of makeapp in action:
{{
bmk makeapp myapp.bmx
bmk makeapp -a -r -o myapp_release myapp.bmx
}}

Note that the debug, release, single threaded and multithreaded options allow for 4 'types' of applications:

* Debug, single threaded (this is the default)
* Debug, multithreaded (use -h option)
* Release, single threaded (use -r option)
* Release, multithreaded (use -r and -h options)

+Makemods

The makemods operation builds a set of modules.

Makemods takes one optional argument: a module filter. This can be a module scope name (to build a subset of modules) or a fully qualified module name (to build an individual module). If the module filter is omitted, than all module are built.

Valid options for makemods are:
[ @Option | @Effect
* @{-a} | Build all modules regardless of timestamps. By default, only modules that have been modified are built.
* @{-d} | Build debug version only. By default, both debug and release versions are built.
* @{-g <architecture>} | Compiles to the specified architecture. (the default is the native for this binary - x86) Options vary depending on the current OS, architecture and installed toolchain. MacOS: x86, x64. Win32: x86, x64. Linux: x86, x64. iOS: x86, x64 (simulator), armv7, arm64. Android: x86, x64, arm, armeabi, armeabiv7a, arm64v8a. RaspberryPi: arm. Emscripten: js.
* @{-h} | Build multithreaded versions. By default, the single threaded version only is built.
* @{-r} | Build release version only. By default, both debug and release versions are built.
* @{-v} | verbose (noisy build)
]

Some examples of makemods in action:
{{
bmk makemods mymods
bmk makemods -a mymods.testmod
}}

+Zapmod

The Zapmod operation compresses a module into a single '.zap' file.

Zapmod takes 2 arguments - the module to zap, and the name of the output file.

For example:
{{
bmk zapmod mymods.testmod testmod.zap
}}

+UnzapMod

Unzapmod installs a module previously zapped with 'Zapmod'.

Unzapmod takes 1 argument - the module zap file to unzap. Note that any matching existing module will be overwritten by this operation. For example:
{{
bmk unzapmod testmod.zap
}}