View source for 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 <tt>build.bat</tt>,
* On Linux, run <tt>./build.sh</tt>.

See the <tt>example</tt> or <tt>template</tt> project for an actual use case.

== Configuration ==

The Build tool configuration's parameters are defined in the '''engine''' (<tt>engine/script/js/setup_global.js</tt>) and can be overwrite by the user at two levels:
* The '''default''' configuration (<tt>projects/default_config.js</tt>), commun for all the projects.
* The '''project''' configuration (<tt>projects/myProject/project_config.js</tt>), 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|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.

{{PARAM|DoClean|Clear all intermediate files and exit|boolean|false}}

{{PARAM|DoCompile|Compile all the project and engine source code. Generate all REL files|boolean|true}}

{{PARAM|DoMake|Link all the project and engine source code. Merge all REL into one IHX file|boolean|true}}

{{PARAM|DoPackage|Generate final binary file (boolean). Binarize the IHX file|boolean|true}}

{{PARAM|DoDeploy|Gathering of all files necessary for the program to work (boolean). Depends on the type of target|boolean|true}}

{{PARAM|DoRun|Start the program automatically at the end of the build|boolean|false}}

=== Path ===

{{PARAM|ProjDir|Project directory|string|}}

{{PARAM|OutDir|Intermediate files directory|string|`${ProjDir}out/`}}

{{PARAM|RootDir|MSXgl root directory|string|}}

{{PARAM|LibDir|Library directory|string|`${RootDir}engine/`}}

{{PARAM|ToolsDir|Tools directory|string|`${RootDir}tools/`}}

=== Tools ===

{{PARAM|Compiler|Path to the C compile program |string|`${ToolsDir}sdcc\bin\sdcc`}}

{{PARAM|Assembler|Path to the assembler program |string|`${ToolsDir}sdcc\bin\sdasz80`}}

{{PARAM|Linker|Path to the linker program |string|`${ToolsDir}sdcc\bin\sdcc`}}

{{PARAM|MakeLib|Path to the program to generate lib file |string|`${ToolsDir}sdcc\bin\sdar`;}}

{{PARAM|Hex2Bin|Path to IHX to binary convertor |string|`${ToolsDir}MSXtk\bin\MSXhex`}}

{{PARAM|MSXDOS|Path to the MSX-DOS files |string|`${ToolsDir}build\MSXDOS`}}

{{PARAM|DskTool|Path to the tool to generate DSK file |string|`${ToolsDir}build\DskTool\dsktool`}}

{{PARAM|Emulator|Path to the emulator to launch the project |string|}}

{{PARAM|Debugger|Path to the debugger to test the project |string|}}

=== Project ===

{{PARAM|ProjName|Project name. Will be use for output filename|string|}}

{{PARAM|ProjModules|List of project modules to build. If empty, ProjName will be added|array|}}

{{PARAM|ProjSegments|Project segments base name. ProjName will be used if not defined|string|}}

{{PARAM|LibModules|List of library modules to build|array|}}

{{PARAM|AddSources|Additional sources to be compiled and linked with the project|array|}}

{{PARAM|Machine|Target MSX machine version|string|"1"}}
<syntaxhighlight lang="txt">
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)
</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"}}
<syntaxhighlight lang="txt">
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
</syntaxhighlight>
More detail: [[Targets]]

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

{{PARAM|ROMDelayBoot|Postpone the ROM startup to let the other ROMs initialize like Disk controller or Network cartridge|boolean|false}}

{{PARAM|InstallRAMISR|Select RAM in slot 0 and install ISR there. For MSX with at least 64 KB of RAM|boolean|false}}

{{PARAM|CustomISR|Type of custom ISR to install. ISR is install in RAM or ROM depending on Target and InstallRAMISR parameters|string|"VBLANK"}}
<syntaxhighlight lang="txt">
VBLANK      V-blank handler
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|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|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|DOSParseArg|Parse MSX-DOS command-line arguments|boolean|true}}

==== Signature ====
{{PARAM|AppSignature|Add application signature to binary data|boolean|false}}

{{PARAM|AppCompany|Application company. Can be 2 character string or 16-bits integer|string/number|"GL"}}

{{PARAM|AppID|Application ID. Can be 2 character string or 16-bits integer (0~65535)|string/number|0}}

{{PARAM|AppExtra|Application extra data. Comma-separated bytes starting with data size|array|}}

<u>Note</u>: See [[AppSignature]] and [[AppExtra]] for more details.

=== Make ===

{{PARAM|BuildLibrary|Force to generate MSXgl static library even if 'msxgl.lib' already exist|bolean|true}}

{{PARAM|Debug|Prepare program for debug|boolean|false}}

{{PARAM|DebugSymbols|Move debug symbols to deployement folder|boolean|false}}

{{PARAM|AllowUndocumented|Allow compiler to generate undocumented Z80 instructions|boolean|true}}

{{PARAM|AsmOptim|Assembler code optimizer ⚠️ WIP|string|"None"}}
<syntaxhighlight lang="txt">
None
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|CompileSkipOld|Skip file if compiled data (REL) is newer than the source code|boolean|false}}

{{PARAM|LinkOpt|Additionnal link options|string|}}

{{PARAM|BuildVersion|Automatic increment of build version in a header file|boolean|false}}

=== Build Tool ===

{{PARAM|Verbose|Activate verbose mode and get more build information|boolean|false}}

{{PARAM|LogStdout|Output build information to the standard console|boolean|true}}

{{PARAM|LogFile|Output build information to a log file|boolean|false}}

{{PARAM|LogFileName|Name of the log file|string|"log_YYYYMMDD_HHMMSS.txt"}}

=== Emulator ===

==== General ====
{{PARAM|EmulMachine|Force the MSX version of the emulated machine|boolean|true}}

{{PARAM|Emul60Hz|Force the emulated machine to be at 60 Hz|boolean|false}}

{{PARAM|EmulFullScreen|Force the emulator to start in fullscreen mode|boolean|false}}

{{PARAM|EmulMute|Disable emulator sound|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|}}

==== Extensions ====
{{PARAM|EmulSCC|Add SCC extension|boolean|false}}

{{PARAM|EmulMSXMusic|Add MSX-Music 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|EmulV9990|Add V9990 video-chip extension|boolean|false}}

==== Input ====
{{PARAM|EmulPortA|Plug a virtual device into the joystick port A|string|}}
<syntaxhighlight lang="txt">
Joystick
Keyboard     // Fake joystick
Mouse
NinjaTap
</syntaxhighlight>

{{PARAM|EmulPortB|Plug a virtual device into the joystick port B|string|}}

== 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 ==

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.