buzz_toolset

This is an old revision of the document!


The most common use of the Buzz toolset is to compile a Buzz script into bytecode executable by the Buzz Virtual Machine. As shown in the above image, the process is composed two sequential transformations:

  • The bzzparse command translates the input script into assembly code.
  • The bzzasm command compiles the annotated assembly code into bytecode, and produces an extra file that contains debug information.

Since it would be tedious to manually execute two commands every time a script is to be compiled, the toolset also offers a command called bzzc that manages the compilation process automatically.

The fourth tool, called bzzdeasm, produces an annotated assembly file from the bytecode and the debug information.

$ bzzparse <infile.bzz> <outfile.basm>

This command compiles the Buzz script infile.bzz into an assembly code file outfile.basm. The assembly code is annotated with debug information that specifies, for each instruction, the corresponding position in the original script file, as well as in any included files.

bzzparse looks into the variable BUZZ_INCLUDE_PATH to get a list of include paths. The paths are expressed as a colon-separated list:

$ export BUZZ_INCLUDE_PATH=path1:path2:...:pathN
$ bzzasm <infile.basm> <outfile.bo> <outfile.bdb>

This command compiles a Buzz assembly code file infile.basm and produces two output files. The first, outfile.bo, is the bytecode to be executed by the Buzz Virtual Machine. The second, outfile.bdb, is a binary file containing debugging information.

$ bzzc [options] <file.bzz>

This command combines bzzparse and bzzasm. It takes as input a script file.bzz and produces two files: file.bo (the bytecode file), and file.bdb (the debugging information file).

bzzc honors BUZZ_INCLUDE_PATH like bzzparse.

In addition, it is possible to specify the path of bzzparse and bzzasm with the environment variables BZZPARSE and BZZASM, respectively. This is usually not necessary, as bzzc looks for these paths automatically. This feature was added to make seamless support of automated build systems like CMake possible.

The bzzc command accepts the following options:

  • -I|--include path1:path2:…:pathN: specifies a list of include paths to append to BUZZ_INCLUDE_PATH
  • -b|--bytecode file.bo: specifies an explicit name for the bytecode file
  • -d|--debug file.bdb: specifies an explicit name for the debugging information file
  • -h|--help: shows help on the command line
$ bzzdeasm <infile.bo> <infile.bdbg> <outfile.basm>

This tool takes as input a bytecode file infile.bo and the corresponding debugging information file infile.bdbg, and produces an assembly code file outfile.basm.

CMake is a popular tool to automated the creation of Makefiles. The Buzz distribution includes two CMake modules that make it possible to discover where Buzz was installed, and to use the toolset to compile Buzz scripts. The CMake modules are installed in $PREFIX/share/buzz/cmake. $PREFIX is the prefix of the Buzz installation, whose default value is /usr/local.

Configuring CMake to Find the Modules

You have two ways to have CMake find the modules.

The first is to set the variable CMAKE_MODULE_PATH to $PREFIX/share/buzz/cmake. This will instruct CMake to go look for these modules in that directory. Assuming $PREFIX is /usr/local, you could write:

set(CMAKE_MODULE_PATH /usr/local/share/buzz/cmake)

The second is to symlink the modules directly into the CMake distribution. Assuming CMake was installed in /usr/local, type:

$ cd /usr/local/share/cmake/Modules
$ ln -s /usr/local/share/buzz/cmake/FindBuzz.cmake
$ ln -s /usr/local/share/buzz/cmake/UseBuzz.cmake
  • buzz_toolset.1460782240.txt.gz
  • Last modified: 2016/04/16 04:50
  • by ilpincy