Build tool

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 using 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. The order of priority is: Project > Default > Engine.

Build parameters

Steps

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: true]

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

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

Assembler: Path to the assembler program [type: string | default: `${ToolsDir}sdcc\bin\sdasz80`]

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

MakeLib: Path to the program to generate lib file [type: string | default: `${ToolsDir}sdcc\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\MSXDOS`]

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

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

Debugger: Path to the debugger to test 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        MSX 1
2        MSX 2
12       MSX 1&2 (dual support)
2K       Korean MSX 2 (SC9 support)
2P       MSX 2+
TR       MSX turbo R
3        MSX 3 (reserved)

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

BIN              .bin    BASIC binary program (8000h~)
BIN_USR          .bin    BASIC USR binary driver (C000h~)
ROM_8K           .rom    8KB ROM in page 1 (4000h ~ 5FFFh)
ROM_8K_P2        .rom    8KB ROM in page 2 (8000h ~ 9FFFh)
ROM_16K          .rom    16KB ROM in page 1 (4000h ~ 7FFFh)
ROM_16K_P2       .rom    16KB ROM in page 2 (8000h ~ BFFFh)
ROM_32K          .rom    32KB ROM in page 1-2 (4000h ~ BFFFh)
ROM_48K          .rom    48KB ROM in page 0-2 (0000h ~ BFFFh). Pages 1-2 visible at start
ROM_48K_ISR      .rom    48KB ROM in page 0-2 (0000h ~ BFFFh). Pages 0-2 visible at start
ROM_64K          .rom    64KB ROM in page 0-3 (0000h ~ FFFFh). Pages 1-2 visible at start
ROM_64K_ISR      .rom    64KB ROM in page 0-3 (0000h ~ FFFFh). Pages 0-2 visible at start
ROM_ASCII8       .rom    128KB ROM using ASCII-8 mapper
ROM_ASCII16      .rom    128KB ROM using ASCII-16 mapper
ROM_KONAMI       .rom    128KB ROM using Konami mapper (8KB segments)
ROM_KONAMI_SCC   .rom    128KB ROM using Konami SCC mapper (8KB segments)
DOS1             .com    MSX-DOS 1 program (0100h~) No direct acces to Main-ROM
DOS2             .com    MSX-DOS 2 program (0100h~) No direct acces to Main-ROM
DOS2_ARG         .com    [WIP] MSX-DOS 2 program (using command line arguments ; 0100h~) No direct acces to Main-ROM.

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]

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

InstallRAMISR: Select RAM in slot 0 and install ISR there. For MSX with at least 64 KB of RAM [type: boolean | default: false]

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)

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

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

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

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

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: ]

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]

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

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]

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"]

Misc

• Batch to JS conversion guide