Build tool
From MSX Game Library
Contents
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: 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
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"]
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]
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]
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 Keyboard Fake joystick Mouse NinjaTap
EmulPortB: Plug a virtual device into the joystick port B [type: string | default: ]