Difference between revisions of "Build tool"

From MSX Game Library

(→‎Configuration)
(→‎Project)
 
(53 intermediate revisions by the same user not shown)
Line 19: Line 19:
 
The value of the parameters redefined in a higher level replaces that of a lower level.
 
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).
+
Some parameters can be overwrite as command-line parameters (see [[#Command-line overwrite|Command-line overwrite]] section).
  
−
The order of priority is: Command-line > Project config > Default config > Engine config.
+
The order of '''priority''' is: Command-line > Project config > Default config > Engine config.
  
 
== Build parameters ==
 
== Build parameters ==
  
−
=== Steps ===
+
=== Stage ===
 +
The build tool is divided into several stages that you can choose to activate or deactivate at will.
  
 
{{PARAM|DoClean|Clear all intermediate files and exit|boolean|false}}
 
{{PARAM|DoClean|Clear all intermediate files and exit|boolean|false}}
Line 84: Line 85:
  
 
{{PARAM|Machine|Target MSX machine version|string|"1"}}
 
{{PARAM|Machine|Target MSX machine version|string|"1"}}
−
1        MSX 1
+
<syntaxhighlight lang="txt">
−
2        MSX 2
+
1        MSX1
−
12      MSX 1&2 (dual support)
+
2        MSX2
−
2K      Korean MSX 2 (SC9 support)
+
12      MSX1 and 2 (multi support)
−
2P      MSX 2+
+
2K      Korean MSX2 (SC9 support)
−
TR      MSX turbo R
+
2P      MSX2+
−
3        MSX 3 (reserved)
+
22P      MSX2 and 2+ (multi support)
 +
122P    MSX1, 2 and 2+ (multi support)
 +
0        MSX0
 +
TR      MSX turbo R
 +
3        MSX3 (reserved)
 +
</syntaxhighlight>
 +
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.
  
 
{{PARAM|Target|Target program format|string|"ROM_32K"}}
 
{{PARAM|Target|Target program format|string|"ROM_32K"}}
−
BIN              .bin    BASIC binary program (8000h~)
+
<syntaxhighlight lang="txt">
−
BIN_USR          .bin    BASIC USR binary driver (C000h~)
+
BIN              .bin    BASIC binary program (starting at 8000h)
−
ROM_8K          .rom    8KB ROM in page 1 (4000h ~ 5FFFh)
+
BIN_USR          .bin    BASIC USR binary driver (starting at C000h)
−
ROM_8K_P2        .rom    8KB ROM in page 2 (8000h ~ 9FFFh)
+
DOS1            .com    MSX-DOS 1 program (starting at 0100h)
−
ROM_16K          .rom    16KB ROM in page 1 (4000h ~ 7FFFh)
+
DOS2            .com    MSX-DOS 2 program (starting at 0100h)
−
ROM_16K_P2      .rom    16KB ROM in page 2 (8000h ~ BFFFh)
+
DOS2_MAPPER      .com    MSX-DOS 2 launcher to RAM mapper (launcher starting at 0100h, program at 4000h)
−
ROM_32K          .rom    32KB ROM in page 1-2 (4000h ~ BFFFh)
+
DOS0            .com    Direct program boot from disk (starting at 0100h)
−
ROM_48K          .rom    48KB ROM in page 0-2 (0000h ~ BFFFh). Pages 1-2 visible at start
+
ROM_8K          .rom    8 KB ROM in page 1 (4000h ~ 5FFFh)
−
ROM_48K_ISR      .rom    48KB ROM in page 0-2 (0000h ~ BFFFh). Pages 0-2 visible at start
+
ROM_8K_P2        .rom    8 KB ROM in page 2 (8000h ~ 9FFFh)
−
ROM_64K          .rom    64KB ROM in page 0-3 (0000h ~ FFFFh). Pages 1-2 visible at start
+
ROM_16K          .rom    16 KB ROM in page 1 (4000h ~ 7FFFh)
−
ROM_64K_ISR      .rom    64KB ROM in page 0-3 (0000h ~ FFFFh). Pages 0-2 visible at start
+
ROM_16K_P2      .rom    16 KB ROM in page 2 (8000h ~ BFFFh)
−
ROM_ASCII8      .rom    128KB ROM using ASCII-8 mapper
+
ROM_32K          .rom    32 KB ROM in page 1&2 (4000h ~ BFFFh)
−
ROM_ASCII16      .rom    128KB ROM using ASCII-16 mapper
+
ROM_48K          .rom    48 KB ROM in page 0-2 (0000h ~ BFFFh)
−
ROM_KONAMI      .rom    128KB ROM using Konami mapper (8KB segments)
+
ROM_48K_ISR      .rom    48 KB ROM in page 0-2 (0000h ~ BFFFh) with ISR replacement
−
ROM_KONAMI_SCC  .rom    128KB ROM using Konami SCC mapper (8KB segments)
+
ROM_64K          .rom    64 KB ROM in page 0-3 (0000h ~ FFFFh)
−
DOS1            .com    MSX-DOS 1 program (0100h~) No direct acces to Main-ROM
+
ROM_64K_ISR      .rom    64 KB ROM in page 0-3 (0000h ~ FFFFh) with ISR replacement
−
DOS2            .com    MSX-DOS 2 program (0100h~) No direct acces to Main-ROM
+
ROM_ASCII8      .rom    ASCII-8: 8 KB segments for a total of 64 KB to 2 MB
−
DOS2_ARG        .com    [WIP] MSX-DOS 2 program (using command line arguments ; 0100h~) No direct acces to Main-ROM.
+
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
 +
</syntaxhighlight>
 
More detail: [[Targets]]
 
More detail: [[Targets]]
  
Line 120: Line 130:
  
 
{{PARAM|CustomISR|Type of custom ISR to install. ISR is install in RAM or ROM depending on Target and InstallRAMISR parameters|string|"VBLANK"}}
 
{{PARAM|CustomISR|Type of custom ISR to install. ISR is install in RAM or ROM depending on Target and InstallRAMISR parameters|string|"VBLANK"}}
−
VBLANK     V-blank handler
+
<syntaxhighlight lang="txt">
−
VHBLANK   V-blank and h-blank handler (V9938 or V9958)
+
VBLANK     V-blank handler
−
V9990     v-blank, h-blank and command end handler (V9990)
+
VHBLANK     V-blank and h-blank handler (V9938 or V9958)
 +
V9990       V-blank, h-blank and command end handler (V9990)
 +
</syntaxhighlight>
 +
Depending on the selected ISR, some functions must be provided by the user:
 +
<syntaxhighlight lang="c">
 +
// 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
 +
</syntaxhighlight>
  
 
{{PARAM|BankedCall|Use automatic banked call and trampoline functions (for mapped ROM)|boolean|false}}
 
{{PARAM|BankedCall|Use automatic banked call and trampoline functions (for mapped ROM)|boolean|false}}
Line 128: Line 154:
 
{{PARAM|ForceRamAddr|Overwrite RAM starting address. For example. 0xE0000 for 8K RAM machine|number|0}}
 
{{PARAM|ForceRamAddr|Overwrite RAM starting address. For example. 0xE0000 for 8K RAM machine|number|0}}
  
−
{{PARAM|DiskFiles|List of data files to copy to disk |array|}}
+
{{PARAM|RawFiles|List of raw data files to be added to the final binary|array|}}
 +
<syntaxhighlight lang="js">
 +
// Sample example
 +
RawFiles = [
 +
    { offset: 0x10000, file:"file1.bin"},
 +
    { segment: 7, file:"file2.bin" },
 +
    { page: 0, file:"file.bin" },
 +
];
 +
</syntaxhighlight>
 +
 
 +
{{PARAM|DiskFiles|List of data files to copy to disk|array|}}
 +
 
 +
{{PARAM|DiskSize|Size of the final disk (.DSK file). Can be "360K" or "720K"|string|"720K"}}
  
 
{{PARAM|USRAddr|BASIC USR driver default address|number|0xC000}}
 
{{PARAM|USRAddr|BASIC USR driver default address|number|0xC000}}
  
 +
{{PARAM|DOSParseArg|Parse MSX-DOS command-line arguments|boolean|true}}
 +
 +
=== Signature ===
 
{{PARAM|AppSignature|Add application signature to binary data|boolean|false}}
 
{{PARAM|AppSignature|Add application signature to binary data|boolean|false}}
  
Line 139: Line 180:
  
 
{{PARAM|AppExtra|Application extra data. Comma-separated bytes starting with data size|array|}}
 
{{PARAM|AppExtra|Application extra data. Comma-separated bytes starting with data size|array|}}
 +
 +
<u>Note</u>: See [[AppSignature]] and [[AppExtra]] for more details.
  
 
=== Make ===
 
=== Make ===
Line 148: Line 191:
 
{{PARAM|DebugSymbols|Move debug symbols to deployement folder|boolean|false}}
 
{{PARAM|DebugSymbols|Move debug symbols to deployement folder|boolean|false}}
  
−
{{PARAM|AsmOptim|Assembler code optimizer ⚠️ WIP|string|None}}
+
{{PARAM|AllowUndocumented|Allow compiler to generate undocumented Z80 instructions|boolean|true}}
−
None
 
−
Peep      SDCC peep hole otpimizer
 
−
MDL        MDL z80 otpimizer
 
  
−
{{PARAM|Optim|Code optimization priority|string|Speed}}
+
{{PARAM|AsmOptim|Assembler code optimizer ⚠️ WIP|string|"None"}}
−
Default
+
<syntaxhighlight lang="txt">
−
Speed
+
None
−
Size
+
Peep    SDCC peep hole otpimizer
 +
MDL      MDL z80 otpimizer
 +
</syntaxhighlight>
 +
 
 +
{{PARAM|Optim|Code optimization priority|string|"Speed"}}
 +
<syntaxhighlight lang="txt">
 +
Default
 +
Speed
 +
Size
 +
</syntaxhighlight>
 +
 
 +
{{PARAM|CompileComplexity|Compile complexity. The higher the most optimized but the slowest to compile. Can be one of the predefine name or a integer value.|string/integer|"Default"}}
 +
<syntaxhighlight lang="txt">
 +
Fast          2000
 +
Default      3000
 +
Optimized    50000
 +
Ultra        200000
 +
Insane        10000000
 +
</syntaxhighlight>
  
 
{{PARAM|CompileOpt|Additionnal compilation flag|string|}}
 
{{PARAM|CompileOpt|Additionnal compilation flag|string|}}
Line 165: Line 223:
  
 
{{PARAM|BuildVersion|Automatic increment of build version in a header file|boolean|false}}
 
{{PARAM|BuildVersion|Automatic increment of build version in a header file|boolean|false}}
 +
 +
=== Localization ===
 +
 +
{{PARAM|LocFiles|List files to be localized|array|}}
 +
 +
{{PARAM|LocOutput|Localization output filename|string|"localization.h"}}
 +
 +
{{PARAM|LocStruct|Localization structure name|string|"g_LocData"}}
 +
 +
{{PARAM|LocSplitDef|Split socalization data and definitions in different files|boolean|false}}
  
 
=== Build Tool ===
 
=== Build Tool ===
Line 175: Line 243:
  
 
{{PARAM|LogFileName|Name of the log file|string|"log_YYYYMMDD_HHMMSS.txt"}}
 
{{PARAM|LogFileName|Name of the log file|string|"log_YYYYMMDD_HHMMSS.txt"}}
 +
 +
=== Analyzer ===
 +
 +
{{PARAM|Analyzer|Execute compiler analyzer|boolean|true}}
 +
 +
{{PARAM|AnalyzerOutput|Analyzer output selection|string|Both}}
 +
<syntaxhighlight lang="txt">
 +
Console    // Output to termial console
 +
File      // Output to file
 +
Both      // Output to file and termial console (default)
 +
</syntaxhighlight>
 +
 +
{{PARAM|AnalyzerReport|Analyzer report elements|string|ASMCV}}
 +
<syntaxhighlight lang="txt">
 +
[A]        // Report areas
 +
[S]        // Report segments
 +
[M]        // Report modules
 +
[C]        // Report code symbols
 +
[V]        // Report variable symbols
 +
</syntaxhighlight>
 +
 +
{{PARAM|AnalyzerSort|Analyzer report sorting|string|Size}}
 +
<syntaxhighlight lang="txt">
 +
None      // No sorting (MAP file order)
 +
Alpha      // Alphanumeric sorting
 +
Size      // Size sorting (default)
 +
</syntaxhighlight>
 +
 +
{{PARAM|AnalyzerCSV|Export analyzer data to CSV file|boolean|false}}
 +
 +
{{PARAM|AnalyzerSeparator|Analyzer CSV file separator|string|","}}
  
 
=== Emulator ===
 
=== Emulator ===
Line 188: Line 287:
  
 
{{PARAM|EmulDebug|Start emulator debugger with program launch|boolean|false}}
 
{{PARAM|EmulDebug|Start emulator debugger with program launch|boolean|false}}
 +
 +
{{PARAM|EmulTurbo|Start emulator in turbo mode|boolean|false}}
  
 
{{PARAM|EmulExtraParam|Emulator extra parameters to be add to command-line. Emulator sotfware specific|string|}}
 
{{PARAM|EmulExtraParam|Emulator extra parameters to be add to command-line. Emulator sotfware specific|string|}}
Line 197: Line 298:
  
 
{{PARAM|EmulMSXAudio|Add MSX-Audio extension|boolean|false}}
 
{{PARAM|EmulMSXAudio|Add MSX-Audio extension|boolean|false}}
 +
 +
{{PARAM|EmulOPL4|Add OPL4 extension|boolean|false}}
  
 
{{PARAM|EmulPSG2|Add second PSG extension|boolean|false}}
 
{{PARAM|EmulPSG2|Add second PSG extension|boolean|false}}
Line 204: Line 307:
 
==== Input ====
 
==== Input ====
 
{{PARAM|EmulPortA|Plug a virtual device into the joystick port A|string|}}
 
{{PARAM|EmulPortA|Plug a virtual device into the joystick port A|string|}}
−
Joystick
+
<syntaxhighlight lang="txt">
−
Keyboard        Fake joystick
+
Joystick
−
Mouse
+
Mouse
−
NinjaTap
+
Paddle
 +
JoyMEga
 +
NinjaTap
 +
</syntaxhighlight>
  
 
{{PARAM|EmulPortB|Plug a virtual device into the joystick port B|string|}}
 
{{PARAM|EmulPortB|Plug a virtual device into the joystick port B|string|}}
Line 213: Line 319:
 
== Command-line overwrite ==
 
== Command-line overwrite ==
  
 +
The followings parameters can be overwrite from command-line parameter when the Build tool script is invoked:
 +
 +
{| class="wikitable"
 +
! Parameter !! Syntax !! Desc. !! Example
 +
|-
 +
| <tt style="font-size:120%;">Target</tt> || <tt>target=XXX</tt> || Overwrite program target type || <tt>target=DOS1</tt> (for MSX-DOS program)
 +
|-
 +
| <tt style="font-size:120%;">Machine</tt> || <tt>machine=XXX</tt> || Overwrite target machine || <tt>machine=2P</tt> (for MSX2+ machine)
 +
|-
 +
| <tt style="font-size:120%;">ProjName</tt> || <tt>projname=XXX</tt> || Overwrite project name || <tt>projname=mygame</tt>
 +
|-
 +
| <tt style="font-size:120%;">ROMSize</tt> || <tt>romsize=XXX</tt> || Overwrite mapped-ROM size || <tt>romsize=256</tt> (for 256 KB mapped-ROM)
 +
|-
 +
| <tt style="font-size:120%;">ROMDelayBoot</tt> || <tt>delay</tt> || Force the delay boot parameter to true || <tt>delay</tt>
 +
|-
 +
| <tt style="font-size:120%;">InstallRAMISR</tt> || <tt>ramisr</tt> || Force the install RAM ISR parameter (switch page 0 to RAM and intall ISR there) || <tt>ramisr</tt>
 +
|}
 +
 +
For example:
 +
<syntaxhighlight lang="bash">
 +
..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js target=%1
 +
</syntaxhighlight>
 +
Allows you to overwrite the build target from the command line. E.g.: <tt>build DOS2</tt> (MSX-DOS2 application) or <tt>build ROM_48K</tt> (48 KB plain-ROM cartridge).
  
 
== Misc ==
 
== Misc ==
  
−
Previously, the Build tool was written in Windows batch. Here is a [[Batch to JS conversion guide|guide to convert the configuration files to use the new Build tool]].
+
Previously, the Build tool was written in Windows batch format.
 +
Here is a [[Batch to JS conversion guide|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.

Latest revision as of 01:12, 13 November 2024

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

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        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_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)
DOS2_MAPPER      .com    MSX-DOS 2 launcher to RAM mapper (launcher starting at 0100h, program at 4000h)
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

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)

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]

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

// Sample example
RawFiles = [
    { offset: 0x10000, file:"file1.bin"},
    { segment: 7, file:"file2.bin" },
    { page: 0, file:"file.bin" },
];

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]

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]

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

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.

Retrieved from "https://aoineko.org/msxgl/index.php?title=Build_tool&oldid=2965"