Chapter2.Installation and usage

Table of Contents

Installation
Getting Started
Usage

Installation

blam is currently available as a binary release in a standard zip file.

Using the Zip

  1. Extract the contents of the blam zip to a directory.

  2. [Optional Step] Add the newly created directory to your PATH variable. (How do I do this on Windows?)

Configuring blam

Before blam can compile applications, you will need to set-up the configuration file called "blam.ini" in the same directory as the executable. This file contains the full path to BlitzMax compilers, one for each platform (Windows, Linux and MacOS).

There is an example "blam.ini" file in the zip directory, but if your paths are different they will need to be updated.

An example configuration file looks something like this:

# Configuration file for blam. [BlitzMax] win32 = c:\Program Files (x86)\blitzmax\bin\bmk.exe linux = /usr/bin/bmk macos = /Applications/BlitzMax/bin/bmk

Getting Started

Once the software has been installed, you can start running build scripts. A build script is an XML file that contains a list of commands to be run. Build scripts are broken into "targets", which are made up of "tasks". Targets are used to break a build file into easy to read chunks, and also to allow a single build file to be capable of carrying out many different tasks.

Each build script must contain:

  • A valid XML header.

  • A project node containing with the project's name and the name of the default target.

  • At least one build target.

Example2.1."Hello World!" as a build file



	
		Hello World!
	

To run this script:

  1. Open a command prompt (e.g. Start -> Run -> "cmd" on Windows)

  2. Type the following (assuming the blam directory was added to the path):

    blam --file=build.xml --target=HelloWorld

    Alternatively, calling blam without any parameters will execute the default build file (build.xml) and the default target (HelloWorld in this example).

This will tell blam to execute the build file using the default target. If blam was installed correctly, the following output will be displayed:

More examples are provided in the "examples" folder of the distribution.

Usage

Quick overview of command line switches and parameters.

Command Line Switches

--help

List all available commands and switches.

-f or --file-name

The name of the build file to run. If this is not specified, blam will search the current directory for files named "build.xml" or "blam.xml".

-l or --list

List all available targets in the build file.

-t or --target

The target in the build file to execute. If none specified, blam will run the default target as defined in the project tag.

--prop:name=value

Set a global property that can be accessed from the build script. Property names and values may contain spaces, but should be enclosed inside quotation (") marks.

Example:

blam -f=my-file.xml --prop:my-property=property-value --prop:someOtherProperty="A value with spaces"

The "my-property" and "someOtherProperty" properties will then be available to all targets and tasks.