View source for Batch to JS conversion guide

Historically, {{MSXGL}} was designed on Windows PC, for users of this platform. The [[Build tool]] was therefore written in Batch language (<tt>.bat</tt>).

To open the library to users of other platforms (Linux and macOS) and overcome the limitations of the Batch language, the Build tool has been entirely rewritten in JavaScript and executed via Node.js.
Everything necessary for the execution of these new scripts being packaged with MSXgl on Windows and Linux, the user has no other software to install. For macOS, SDCC and Node.js must be [[Install/macOS|installed separately]].

This guide is intended for users who have already created an MSXgl project and who would like to convert their project configuration to benefit from the new version of the Build tool (which I strongly recommend).

== Convert Batch project to JS ==

# Rename your <tt>build.bat</tt> to <tt>project_config.js</tt> ''(You can duplicate the file if you want to keep the batch file as a backup)''
# Open <tt>project_config.js</tt> an start the Batch to JS conversion:
#* Convert comment:
#** Replace any '<tt>::</tt>' by '<tt>//</tt>'.
#** Replace any '<tt>REM</tt>' by '<tt>//</tt>'.
#* Remove '<tt>@echo off</tt>', '<tt>call ..\default_config.cmd %0</tt>' and the final '<tt>call %LibDir%\script\build.cmd</tt>'.
#* Remove all the '<tt>set </tt>' before the parameter name.
#* Convert parameter value depends on the value type:
#** Number: Nothing to do.
#** Boolean: You can keep '<tt>1</tt>' and '<tt>0</tt>' value but for a better readability, it is recommended to use the values '<tt>true</tt>' and '<tt>false</tt>' instead.
#** String: Enclose the value in parenthesis. For example, '<tt>ProjName=template</tt>' become '<tt>ProjName = "template"</tt>' ''(space are not mandatory)''.
#** Array: The array values must be converted according to their type (number, string, ...) but the array itself must be enclose with the '<tt>[]</tt>' characters.<br/>For example, '<tt>LibModules=system,bios,vdp</tt>' become '<tt>LibModules = [ "system", "bios", "vdp" ]</tt>' ''(space are not mandatory)''.
#* Convert variable (if any) by replacing '<tt>%MyVariable%</tt>' by '<tt>MyVariable</tt>'.<br/>If you want to include a variable into a string, you have to enclose the string with '<tt>``</tt>' and then you can put your variable in the string using the '<tt>${MyVariable}</tt>' syntax.
#* All '<tt>\</tt>' characters in file path must be replace by '<tt>/</tt>'.

If you need some help to convert your project, don't hesitate to join the [https://discord.gg/pMeadGfv8E MSXgl's Discord server].

=== Example ===

<div style="display:flex; flex-direction:row; flex-wrap:wrap;"><div style="flex:1; min-width:512px;">
Batch version:‎<syntaxhighlight lang="batch">
:: ____________________________
:: ██▀▀█▀▀██▀▀▀▀▀▀▀█▀▀█        │   ▄▄▄                ▄▄
:: ██  ▀  █▄  ▀██▄ ▀ ▄█ ▄▀▀ █  │  ▀█▄  ▄▀██ ▄█▄█ ██▀▄ ██  ▄███
:: █  █ █  ▀▀  ▄█  █  █ ▀▄█ █▄ │  ▄▄█▀ ▀▄██ ██ █ ██▀  ▀█▄ ▀█▄▄
:: ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀────────┘                 ▀▀
::  by Guillaume 'Aoineko' Blanchard under CC BY-SA license
::─────────────────────────────────────────────────────────────────────────────
@echo off

::─────────────────────────────────────────────────────────────────────────────
:: Build Tool configuration
::─────────────────────────────────────────────────────────────────────────────
call ..\default_config.cmd %0

::*****************************************************************************
:: TOOLS SETTINGS
::*****************************************************************************

set Emulator=%ToolsDir%\OpenMSX\openmsx.exe
REM set Debugger=%ToolsDir%\OpenMSX\Debugger\openmsx-debugger.exe

::*****************************************************************************
:: PROJECT SETTINGS
::*****************************************************************************

:: Project name (will be use for output filename)
set ProjName=example

:: Project modules to build (use ProjName if not defined)
set ProjModules=%ProjName%

:: List of modules to link
set LibModules=system,bios,vdp,print,input,memory,game,game_pawn,math,string

:: MSX machine version
set Machine=1

:: Program media target
set Target=ROM_32K

:: ROM mapper size (from 64 to 4096). Must be a multiple of 8 or 16 depending on the mapper type
set ROMSize=

:: Postpone the ROM startup to let the other ROMs initialize (BDOS for example) (0=false, 1=true)
REM set ROMDelayBoot=0

:: Set RAM in slot 0 and install ISR there (0=false, 1=true)
REM set InstallRAMISR=0

:: Use banked call and trampoline functions (0=false, 1=true)
REM set BankedCall=0

:: Overwrite RAM starting address (e.g. 0xE0000 for 8K RAM machine)
REM set ForceRamAddr=

:: Data to copy to disk (comma separated list)
REM set DiskFiles=

:: Add application signature to binary data (0=false, 1=true)
set AppSignature=1

:: Application company
set AppCompany="PP"

:: Application ID (0~65535)
set AppID="EX"

::*******************************************************************************
:: MAKE SETTINGS
::*******************************************************************************

:: Use static MSXgl library (0=false, 1=true)
REM set BuildLibrary=0

:: Set debug flag (0=false, 1=true)
set Debug=1

:: Assembler code optimizer
:: - None
:: - PeepHole	SDCC otpimizer
:: - MDL		MDL z80 otpimizer
REM set AsmOptim=None

:: Optim:
:: - Default
:: - Speed
:: - Size
REM set Optim=Speed

:: Additionnal compilation flag
REM set CompileOpt=

:: Skip file if compile data is newer than the (0=false, 1=true)
set CompileSkipOld=0

:: Compile verbose mode (0=false, 1=true)
REM set Verbose=0

:: Update build version header file
set BuildVersion=1

::*******************************************************************************
:: EMULATOR SETINGS
::*******************************************************************************

:: Emulator options: 0 or 1
set EmulMachine=0
REM set Emul60Hz=0
REM set EmulFullScreen=0
REM set EmulMute=0
set EmulDebug=1

:: Emulator extensions: 0 or 1
REM set EmulSCC=0
REM set EmulMSXMusic=0
REM set EmulMSXAudio=0
REM set EmulPSG2=0
REM set EmulV9990=0

:: Emulator port: joystick, mouse, keyboard (fake joystick)
REM set EmulPortA=
REM set EmulPortB=

:: Emulator extra parameters to be add to command-line (emulator sotfware specific)
REM set EmulExtraParam=

::*******************************************************************************
:: BUILD STEPS
::*******************************************************************************

set DoClean=0
set DoCompile=1
set DoMake=1
set DoPackage=1
set DoDeploy=1
set DoRun=1

::*****************************************************************************
:: START BUILD
::*****************************************************************************
call %LibDir%\script\build.cmd
‎</syntaxhighlight>
</div><div style="flex:1; min-width:512px;">
JS version:‎<syntaxhighlight lang="js">
// ____________________________
// ██▀▀█▀▀██▀▀▀▀▀▀▀█▀▀█        │   ▄▄▄                ▄▄
// ██  ▀  █▄  ▀██▄ ▀ ▄█ ▄▀▀ █  │  ▀█▄  ▄▀██ ▄█▄█ ██▀▄ ██  ▄███
// █  █ █  ▀▀  ▄█  █  █ ▀▄█ █▄ │  ▄▄█▀ ▀▄██ ██ █ ██▀  ▀█▄ ▀█▄▄
// ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀────────┘                 ▀▀
//  by Guillaume 'Aoineko' Blanchard under CC BY-SA license
//─────────────────────────────────────────────────────────────────────────────

//*****************************************************************************
// TOOLS SETTINGS
//*****************************************************************************

Emulator = `${ToolsDir}OpenMSX/openmsx.exe`;
// Debugger = `${ToolsDir}OpenMSX/Debugger/openmsx-debugger.exe`;

//*****************************************************************************
// PROJECT SETTINGS
//*****************************************************************************

//-- Project name (will be use for output filename)
ProjName = "example";

//-- Project modules to build (use ProjName if not defined)
ProjModules = [ ProjName ];

//-- List of modules to link
LibModules = [ "system", "bios", "vdp", "print" ,"input" ,"memory" ,"game" ,"game_pawn" ,"math" ,"string" ];

//-- MSX machine version
Machine = "1";

//-- Program media target
Target = "ROM_32K";

//-- ROM mapper size (from 64 to 4096). Must be a multiple of 8 or 16 depending on the mapper type
// ROMSize = 

//-- Postpone the ROM startup to let the other ROMs initialize (BDOS for example) (0 = false, 1 = true)
// ROMDelayBoot = 0

//-- RAM in slot 0 and install ISR there (0 = false, 1 = true)
// InstallRAMISR = 0

//-- Use banked call and trampoline functions (0 = false, 1 = true)
// BankedCall = 0

//-- Overwrite RAM starting address (e.g. 0xE0000 for 8K RAM machine)
// ForceRamAddr = 

//-- Data to copy to disk (comma separated list)
// DiskFiles = [];

//-- Add application signature to binary data (0 = false, 1 = true)
AppSignature = true;

//-- Application company
AppCompany = "PP";

//-- Application ID (0~65535)
AppID = "EX";

//*******************************************************************************
// MAKE SETTINGS
//*******************************************************************************

//-- Use static MSXgl library (0 = false, 1 = true)
// BuildLibrary = false;

//-- Debug flag (0 = false, 1 = true)
// Debug = false;

//-- Assembler code optimizer
// - None
// - PeepHole	SDCC otpimizer
// - MDL		MDL z80 otpimizer
// AsmOptim = "";

//-- Optim:
// - Default
// - Speed
// - Size
// Optim = "Speed";

//-- Additionnal compilation flag
// CompileOpt = "";

//-- Skip file if compile data is newer than the (0 = false, 1 = true)
CompileSkipOld = false;

//-- Compile verbose mode (0 = false, 1 = true)
Verbose = true;

//-- Update build version header file
BuildVersion = true;

//*******************************************************************************
// EMULATOR SETINGS
//*******************************************************************************

//-- Emulator options: 0 or 1
EmulMachine = false;
// Emul60Hz = false;
// EmulFullScreen = false;
// EmulMute = false;
EmulDebug = true;

//-- Emulator extensions: 0 or 1
// EmulSCC = false;
// EmulMSXMusic = false;
// EmulMSXAudio = false;
// EmulPSG2 = false;
// EmulV9990 = false;

//-- Emulator port: joystick, mouse, keyboard (fake joystick)
// EmulPortA = "";
// EmulPortB = "";

//-- Emulator extra parameters to be add to command-line (emulator sotfware specific)
// EmulExtraParam = "";

//*******************************************************************************
// BUILD STEPS
//*******************************************************************************

DoClean   = false;
DoCompile = true;
DoMake    = true;
DoPackage = true;
DoDeploy  = true;
DoRun     = true;
‎</syntaxhighlight>
</div></div>

== Create new build file ==

Then, you can create a file to execute the build. Filename and content depends on the plateform:

<div style="display:flex; flex-direction:row; flex-wrap:wrap;"><div style="flex:1; min-width:512px;">'''Windows''': <tt>build.bat</tt>‎<syntaxhighlight lang="batch">
:: ____________________________
:: ██▀▀█▀▀██▀▀▀▀▀▀▀█▀▀█        │   ▄▄▄                ▄▄      
:: ██  ▀  █▄  ▀██▄ ▀ ▄█ ▄▀▀ █  │  ▀█▄  ▄▀██ ▄█▄█ ██▀▄ ██  ▄███
:: █  █ █  ▀▀  ▄█  █  █ ▀▄█ █▄ │  ▄▄█▀ ▀▄██ ██ █ ██▀  ▀█▄ ▀█▄▄
:: ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀────────┘                 ▀▀
::  by Guillaume 'Aoineko' Blanchard under CC BY-SA license
::────────────────────────────────────────────────────────────────────
@echo off

cls

..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js target=%1‎</syntaxhighlight>
Usage example:
* <tt>build</tt> <small>(execute build with default option)</small>
* <tt>build DOS2</tt> <small>(execute build with target overwrite)</small>
</div><div style="flex:1; min-width:512px;">'''Linux''' or '''macOS''': <tt>build.sh</tt>‎<syntaxhighlight lang="batch">
#!/bin/bash
# ____________________________
# ██▀▀█▀▀██▀▀▀▀▀▀▀█▀▀█        │   ▄▄▄                ▄▄
# ██  ▀  █▄  ▀██▄ ▀ ▄█ ▄▀▀ █  │  ▀█▄  ▄▀██ ▄█▄█ ██▀▄ ██  ▄███
# █  █ █  ▀▀  ▄█  █  █ ▀▄█ █▄ │  ▄▄█▀ ▀▄██ ██ █ ██▀  ▀█▄ ▀█▄▄
# ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀────────┘                 ▀▀
#  by Guillaume 'Aoineko' Blanchard under CC BY-SA license
#────────────────────────────────────────────────────────────────────
clear

if type -P node; then
	node ../../engine/script/js/build.js target=$1
else
	../../tools/build/Node/node ../../engine/script/js/build.js target=$1
fi‎</syntaxhighlight>
Usage example:
* <tt>./build</tt> <small>(execute build with default option)</small>
* <tt>./build DOS2</tt> <small>(execute build with target overwrite)</small>
</div></div>