Build tool

The Build tool is the MSXGL script that will create your final program for MSX.

It is fully configurable by the user. For example, it is here that we can choose whether we want our game to be available in ROM, MSX-DOS or BASIC binary format. Or if our program should be MSX1 compatible or only MSX2+ for example.

The Build tool is written in JavaScript and executed via Node.js. All the programs needed to run the script are available in MSXgl and the user does not need to install anything.

Build tool is started from the project directory via a script that depends on the platform:

• On Windows, run build.bat,
• On Linux, run ./build.sh.

See the example or template project for an actual use case.

Configuration

The Build tool configuration's parameters are defined in the engine (engine/script/js/setup_global.js) and can be overwrite by the user at two levels:

• The default configuration (projects/default_config.js), commun for all the projects.
• The project configuration (projects/myProject/project_config.js), specific for a given project.

The value of the parameters redefined in a higher level replaces that of a lower level.

Some parameters can be overwrite as command-line parameters (see Command-line overwrite section).

The order of priority is: Command-line > Project config > Default config > Engine config.

Build parameters

Stage

The build tool is divided into several stages that you can choose to activate or deactivate at will.

DoClean: Clear all intermediate files and exit [type: boolean | default: false]

DoCompile: Compile all the project and engine source code. Generate all REL files [type: boolean | default: true]

DoMake: Link all the project and engine source code. Merge all REL into one IHX file [type: boolean | default: true]

DoPackage: Generate final binary file (boolean). Binarize the IHX file [type: boolean | default: true]

DoDeploy: Gathering of all files necessary for the program to work (boolean). Depends on the type of target [type: boolean | default: true]

DoRun: Start the program automatically at the end of the build [type: boolean | default: false]

Path

ProjDir: Project directory [type: string | default: ]

OutDir: Intermediate files directory [type: string | default: `${ProjDir}out/`]

RootDir: MSXgl root directory [type: string | default: ]

LibDir: Library directory [type: string | default: `${RootDir}engine/`]

ToolsDir: Tools directory [type: string | default: `${RootDir}tools/`]

Tools

SDCCPath: Path to SDCC tools chain [type: string | default: `${ToolsDir}sdcc/`]

Compiler: Path to the C compile program [type: string | default: `${SDCCPath}bin/sdcc`]

Assembler: Path to the assembler program [type: string | default: `${SDCCPath}bin/sdasz80`]

Linker: Path to the linker program [type: string | default: `${SDCCPath}bin/sdcc`]

MakeLib: Path to the program to generate lib file [type: string | default: `${SDCCPath}bin/sdar`]

Hex2Bin: Path to IHX to binary convertor [type: string | default: `${ToolsDir}MSXtk/bin/MSXhex`]

MSXDOS: Path to the MSX-DOS files [type: string | default: `${ToolsDir}build/DOS/`]

DskTool: Path to the tool to generate DSK file [type: string | default: `${ToolsDir}build/msxtar/msxtar`]

Emulator: Path to the emulator to launch the project [type: string | default: ]

Project

ProjName: Project name. Will be use for output filename [type: string | default: ]

ProjModules: List of project modules to build. If empty, ProjName will be added [type: array | default: ]

ProjSegments: Project segments base name. ProjName will be used if not defined [type: string | default: ]

LibModules: List of library modules to build [type: array | default: ]

AddSources: Additional sources to be compiled and linked with the project [type: array | default: ]

Machine: Target MSX machine version [type: string | default: "1"]

//   - 1        MSX1
//   - 2        MSX2
//   - 12       MSX1 and 2 (multi support)
//   - 2K       Korean MSX2 (SC9 support)
//   - 2P       MSX2+
//   - 22P      MSX2 and 2+ (multi support)
//   - 122P     MSX1, 2 and 2+ (multi support)
//   - 0        MSX0
//   - TR       MSX turbo R
//   - 3        MSX3 (reserved)

Multi support means that the application can use the features of all supported MSX generations. The user must detect the MSX version at runtime and adjust the program accordingly.

Target: Target program format [type: string | default: "ROM_32K"]

//   - BIN              .bin    BASIC binary program (starting at 8000h)
//   - BIN_DISK         .bin    BASIC binary program (starting at 8000h) on disk
//   - BIN_TAPE         .bin    BASIC binary program (starting at 8000h) on tape
//   - BIN_USR          .bin    BASIC USR binary driver (starting at C000h)
//   - DOS1             .com    MSX-DOS 1 program (starting at 0100h)
//   - DOS2             .com    MSX-DOS 2 program (starting at 0100h)
//   - DOS0             .com    Direct program boot from disk (starting at 0100h)
//   - ROM_8K           .rom    8 KB ROM in page 1 (4000h ~ 5FFFh)
//   - ROM_8K_P2        .rom    8 KB ROM in page 2 (8000h ~ 9FFFh)
//   - ROM_16K          .rom    16 KB ROM in page 1 (4000h ~ 7FFFh)
//   - ROM_16K_P2       .rom    16 KB ROM in page 2 (8000h ~ BFFFh)
//   - ROM_32K          .rom    32 KB ROM in page 1&2 (4000h ~ BFFFh)
//   - ROM_48K          .rom    48 KB ROM in page 0-2 (0000h ~ BFFFh)
//   - ROM_48K_ISR      .rom    48 KB ROM in page 0-2 (0000h ~ BFFFh) with ISR replacement
//   - ROM_64K          .rom    64 KB ROM in page 0-3 (0000h ~ FFFFh)
//   - ROM_64K_ISR      .rom    64 KB ROM in page 0-3 (0000h ~ FFFFh) with ISR replacement
//   - ROM_ASCII8       .rom    ASCII-8: 8 KB segments for a total of 64 KB to 2 MB
//   - ROM_ASCII16      .rom    ASCII-16: 16 KB segments for a total of 64 KB to 4 MB
//   - ROM_KONAMI       .rom    Konami MegaROM (aka Konami4): 8 KB segments for a total of 64 KB to 2 MB
//   - ROM_KONAMI_SCC   .rom    Konami MegaROM SCC (aka Konami5): 8 KB segments for a total of 64 KB to 2 MB
//   - ROM_NEO8         .rom    NEO-8: 8 KB segments for a total of 1 MB to 32 MB
//   - ROM_NEO16        .rom    NEO-16: 16 KB segments for a total of 1 MB to 64 MB

More detail: Targets

ROMSize: ROM mapper total size in KB. Must be a multiple of 8 or 16 depending on the mapper type (from 64 to 4096) [type: number | default: 128]

ROMMainSegments: Number of segments in the main program of a mapped-ROM. 0 means 'number of segments to fill 32 KB of ROM [type: number | default: 0]

ROMDelayBoot: Postpone the ROM startup to let the other ROMs initialize like Disk controller or Network cartridge [type: boolean | default: false]

AddROMSignature: Add a ROM signature to help flasher and emulator to detect the ROM type properly [type: boolean | default: false]

InstallRAMISR: Select RAM in slot 0 and install ISR and optional code there. For MSX with at least 64 KB of RAM [type: string | default: "RAM0_NONE"]

//   - RAM0_NONE       Don't install anything in RAM 
//   - RAM0_ISR        Install only ISR
//   - RAM0_SEGMENT    Install ISR and segment data (for mapped-ROM)

For mode detail about usage of RAM0_SEGMENT, check this document.

CustomISR: Type of custom ISR to install. ISR is install in RAM or ROM depending on Target and InstallRAMISR parameters [type: string | default: "VBLANK"]

//   - VBLANK     V-blank handler
//   - VHBLANK    V-blank and h-blank handler (V9938 or V9958)
//   - V9990      V-blank, h-blank and command end handler (V9990)

Depending on the selected ISR, some functions must be provided by the user:

// CustomISR = "VBLANK"
VDP_InterruptHandler(); // V-blank interrupt

// CustomISR = "VHBLANK"
VDP_InterruptHandler(); // V-blank interrupt
VDP_HBlankHandler();    // H-blank interrupt

// CustomISR = "V9990"
V9_InterruptVBlank();   // V-blank interrupt
V9_InterruptHBlank();   // H-blank interrupt
V9_InterruptCommand();  // Command end interrupt

BankedCall: Use automatic banked call and trampoline functions (for mapped ROM) [type: boolean | default: false]

ForceCodeAddr: Overwrite code starting address. For example. 0xE0000 for a driver in RAM [type: number | default: 0]

ForceRamAddr: Overwrite RAM starting address. For example. 0xE0000 for 8K RAM machine [type: number | default: 0]

RawFiles: List of raw data files to be added to the final binary [type: array | default: ] Raw files can be added to final binary by defining 3 types of position: offset, segment or page.

// Sample example
RawFiles = [
    { offset: 0x10000, file: "file1.bin" }, // Offset from final binary start
    { segment: 7, file: "file2.bin" },      // Segment number for mapped-ROM
    { page: 0, file: "file.bin" },          // Page number (16 KB) in the final binary
];

DiskFiles: List of data files to copy to disk [type: array | default: ]

DiskSize: Size of the final disk (.DSK file). Can be "360K" or "720K" [type: string | default: "720K"]

USRAddr: BASIC USR driver default address [type: number | default: 0xC000]

DOSParseArg: Parse MSX-DOS command-line arguments [type: boolean | default: true]

Signature

AppSignature: Add application signature to binary data [type: boolean | default: false]

AppCompany: Application company. Can be 2 character string or 16-bits integer [type: string/number | default: "GL"]

AppID: Application ID. Can be 2 character string or 16-bits integer (0~65535) [type: string/number | default: 0]

AppExtra: Application extra data. Comma-separated bytes starting with data size [type: array | default: ]

Note: See AppSignature and AppExtra for more details.

Make

BuildLibrary: Force to generate MSXgl static library even if 'msxgl.lib' already exist [type: bolean | default: true]

Debug: Prepare program for debug [type: boolean | default: false]

DebugSymbols: Move debug symbols to deployement folder [type: boolean | default: false]

AllowUndocumented: Allow compiler to generate undocumented Z80 instructions [type: boolean | default: true]

AsmOptim: Assembler code optimizer ⚠️ WIP [type: string | default: "None"]

//   - None
//   - Peep       SDCC peep hole otpimizer
//   - MDL        MDL z80 otpimizer

Optim: Code optimization priority [type: string | default: "Speed"]

//   - Default
//   - Speed
//   - Size

CompileComplexity: Compile complexity. The higher the most optimized but the slowest to compile. Can be one of the predefine name or a integer value. [type: string/integer | default: "Default"]

//   - Fast              2000
//   - Default           3000
//   - Optimized        50000
//   - Ultra           200000
//   - Insane        10000000

CompileOpt: Additionnal compilation flag [type: string | default: ]

CompileSkipOld: Skip file if compiled data (REL) is newer than the source code [type: boolean | default: false]

LinkOpt: Additionnal link options [type: string | default: ]

BuildVersion: Automatic increment of build version in a header file [type: boolean | default: false]

PackSegments: Package all segments into a lib file to reduce the number of files to link [type: boolean | default: false]

HexBinOpt: Additionnal options of Hex to Binary convertor [type: string | default: ""]

PreBuildScripts: Command lines to be executed before the build process [type: array | default: []]

PostBuildScripts: Command lines to be executed after the build process [type: array | default: []]

Localization

LocFiles: List files to be localized [type: array | default: ]

LocOutput: Localization output filename [type: string | default: "localization.h"]

LocStruct: Localization structure name [type: string | default: "g_LocData"]

LocSplitDef: Split socalization data and definitions in different files [type: boolean | default: false]

For example:

//-- List files to be localized (array)
LocFiles = [ "translate_en.ini", "translate_fr.ini", "translate_ja.ini" ];

//-- Localization output filename (string)
LocOutput = "data/translate.h";

//-- Localization structure name (string)
LocStruct = "g_TransData";

//-- Split socalization data and definitions in different files (boolean)
LocSplitDef = true;

Build Tool

Verbose: Activate verbose mode and get more build information [type: boolean | default: false]

LogStdout: Output build information to the standard console [type: boolean | default: true]

LogFile: Output build information to a log file [type: boolean | default: false]

LogFileName: Name of the log file [type: string | default: "log_YYYYMMDD_HHMMSS.txt"]

Analyzer

Analyzer: Execute compiler analyzer [type: boolean | default: true]

AnalyzerOutput: Analyzer output selection [type: string | default: Both]

//   - Console    Output to termial console
//   - File       Output to file
//   - Both       Output to file and termial console (default)

AnalyzerReport: Analyzer report elements [type: string | default: ASMCV]

//   - [A]        Report areas
//   - [S]        Report segments
//   - [M]        Report modules
//   - [C]        Report code symbols
//   - [V]        Report variable symbols

AnalyzerSort: Analyzer report sorting [type: string | default: Size]

//   - None       No sorting (MAP file order)
//   - Alpha      Alphanumeric sorting
//   - Size       Size sorting (default)

AnalyzerCSV: Export analyzer data to CSV file [type: boolean | default: false]

AnalyzerSeparator: Analyzer CSV file separator [type: string | default: ","]

Emulator

General

EmulMachine: Force the MSX version of the emulated machine [type: boolean | default: true]

Emul60Hz: Force the emulated machine to be at 60 Hz [type: boolean | default: false]

EmulFullScreen: Force the emulator to start in fullscreen mode [type: boolean | default: false]

EmulMute: Disable emulator sound [type: boolean | default: false]

EmulDebug: Start emulator debugger with program launch [type: boolean | default: false]

EmulTurbo: Start emulator in turbo mode [type: boolean | default: false]

EmulExtraParam: Emulator extra parameters to be add to command-line. Emulator sotfware specific [type: string | default: ]

Extensions

EmulSCC: Add SCC extension [type: boolean | default: false]

EmulMSXMusic: Add MSX-Music extension [type: boolean | default: false]

EmulMSXAudio: Add MSX-Audio extension [type: boolean | default: false]

EmulOPL4: Add OPL4 extension [type: boolean | default: false]

EmulPSG2: Add second PSG extension [type: boolean | default: false]

EmulV9990: Add V9990 video-chip extension [type: boolean | default: false]

Input

EmulPortA: Plug a virtual device into the joystick port A [type: string | default: ]

//   - Joystick
//   - Mouse
//   - Paddle
//   - JoyMega
//   - NinjaTap

EmulPortB: Plug a virtual device into the joystick port B [type: string | default: ]

//   - Joystick
//   - Mouse
//   - Paddle
//   - JoyMega
//   - NinjaTap

Run device

RunDevice: Run device like Easy-USB [type: string | default: ""]

RunDeviceOpt: Run device option [type: string | default: ""]

Command-line overwrite

The followings parameters can be overwrite from command-line parameter when the Build tool script is invoked:

Parameter	Syntax	Desc.	Example
Target	target=XXX	Overwrite program target type	target=DOS1 (for MSX-DOS program)
Machine	machine=XXX	Overwrite target machine	machine=2P (for MSX2+ machine)
ProjName	projname=XXX	Overwrite project name	projname=mygame
ROMSize	romsize=XXX	Overwrite mapped-ROM size	romsize=256 (for 256 KB mapped-ROM)
ROMDelayBoot	delay	Force the delay boot parameter to true	delay
InstallRAMISR	ramisr	Force the install RAM ISR parameter (switch page 0 to RAM and intall ISR there)	ramisr

For example:

..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js target=%1

Allows you to overwrite the build target from the command line. E.g.: build DOS2 (MSX-DOS2 application) or build ROM_48K (48 KB plain-ROM cartridge).

Misc

Previously, the Build tool was written in Windows batch format. Here is a guide to convert the configuration files to use the new Build tool.

⚠️ Old batch version of the build tool is no longer supported start from MSXgl 1.0.1 version. Please update your project configuration.