Installation

The FXCoreMP tools enhance the function of the FXCore assembler tools supplied by Experimental Noize. It is required that those base assembler tools be installed before installing and configuring FXCoreMP. Verify that the assembler tools are working before proceeding with this installation.

Installing the FXCoreMP tools begins with unzipping the install.zip file found on the latest release page into an empty directory. This will unpack several files and subdirectories that are used in the following configuration steps.

= Configuring the Macro/TOON Processor

In general the macro (and TOON) processor is used as part of a sequence of tools (the "tool chain") to completely assemble source code into a HEX file suitable for loading into the FXCore. The tool chain consists of several programs each of which takes an input file, performs some transformation on it, and writes an output file, which is then the input for the next program in the chain.

It is recommended that the macro processor be the first tool in the chain as it allows macros (and TOON syntax statements) to expand into code that could use FXCore library functions. The sequence of tools to complete an assembly process is shown below. The file extensions shown are only by convention but helps identify files that are built at each stage of the process. This can aid debugging assembler errors.

Step	Input File	Program	Output File
1	myfile.xfc	Text Editor Notepad++	myfile.xfc
2	myfile.xfc	Macro+TOON Processor FXCoreMP	myfile.xfc-mp
3	myfile.xfc-mp	FXCore Preprocessor FXCorePreProc	myfile.fxo
4	myfile.fxo	Assembler FXCoreCmdAsm	myfile.hex

At this time FXCoreMP has been tested only on Windows. Since there is nothing inherently platform specific about it, it should be possible to run it on any platform that supports Java including Windows, MacOS, and Linux.

The following sections describe how to install the Java runtime environment, FXCoreMP, and modify the assembler scripts to run FXCoreMP as the first step in the tool chain.

Java Installation

The FXCoreMP program is written in Java and requires a Java runtime to be installed. Any Java version 17 or above should work (see the OpenJDK site for current Java version downloads for most platforms). To verify your Java installation run the command java --version from a command line. If the command is not found you need to add it to your PATH or install Java on your system. If it is found, verify the version is at least 17. For example:

> java --version
java 18 2022-03-22
Java(TM) SE Runtime Environment (build 18+36-2087)
Java HotSpot(TM) 64-Bit Server VM (build 18+36-2087, mixed mode, sharing)

Macro/TOON Processor Configuration

The macro and TOON processor is fully contained in a single JAR file (FXCoreMP.jar). Several Windows CMD files are provided to run it, or it can be invoked as part of the tool chain (recommended) from the assemble.cmd script supplied with the Experimental Noize tools.

The following Windows .CMD scripts are provided in the root directory of the install ZIP:

• macro <input-file> <output-file> This runs the macro processor followed by the TOON processor on the given input file. The final resulting source code is written to the output file.
• toon2asm <input-file> <output-file> This translates any TOON statements in the input file to FXCore assembler statements in the output file. Any line that is not a TOON statement is passed to the output file unchanged.
• asm2toon <input-file> <output-file> This runs the TOON translator in "reverse" mode. It translates any FXCore assembler statements in the input file to equivalent TOON statements in the output file. Any input line that has no TOON translation or is otherwise not recognized is passed to the output unchanged.
• fxcoremp-assemble <args> This script runs the complete tool chain of macro processor, TOON processor, FXCore preprocessor, and FXCore assembler. The result is a HEX file ready for programming the FXCore. See the comments in the script for the list of arguments. This script is similar to that provided in the FXCore toolset, but places all build files in a /bin directory so the source directory remains unmodified. This can be helpful when using a source management system like git because you can easily exclude the entire /bin directory from version control. This is the preferred way to run the tool chain if using the Eclipse IDE for development.

Example:

C:\temp>macro "MyPgm.fxc" "MyPgm.fxc-mp"
FXCoreMP processing completed (macros, toon [TOON-->ASM])
  Errors:             0
  Included files:     0
  Macro definitions:  2
  Output lines:       214 (C:\temp\MyPgm.fxc-mp)

If file names do not include a path, the current directory is assumed. For all the above commands it is recommended that the file names be enclosed in double quotes ".

It is also possible to directly invoke the program without a script. This invocation may be preferred when integrating into an existing toolchain.

java -jar FXCoreMP.jar "input-file" "output-file" --nomacro --notoon --annotate --reversetoon --debug=info

The -- arguments are optional:

• --nomacro Do not run the macro processor. If not specified, macro processing is run.
• --notoon Do not run the TOON processor. If not specified, TOON processing is run.
• --reversetoon This options runs a reverse-toon translation, that is, it reads in FXCore assembler statements and writes out equivalent TOON statements. This can be used to quickly convert existing assembler programs into the TOON format without manual recoding.
• --debug=info Causes the program to output a summary of the translation when it completes, otherwise there is no console output unless an error occurs.

If no options are specified, the macro processor is run first, followed by the TOON processor to produce assembler-ready source. Nothing is written to the console.

To run this in a tool chain and detect failures, the TOON translator will set a process exit code as follows:

• 0 No errors, output file has been written
• 1 Input files are not specified or not found
• 2 Syntax error in the input file
• 3 An unexpected failure

Notepad++ Syntax Highlighting for Macros and TOON

The FXCore assembler tools from Experimental Noize include configuration files for Notepad++ on Windows for editing assembler files. The configuration files supply syntax highlighting instructions for the editor. This project includes an updated configuration file notepadpp/FXCoreAsmUDL.xml which adds syntax highlighting support for macros and TOON statements. This XML file should be copied into the FXCore tools `userDefinedLangs' subdirectory and replaces the one supplied by Experimental Noize. This allows Notepad++ to properly syntax color TOON and macro statements:

• $macro and $endmacro are colored brown and can be collapsed with +/- markers in the left gutter of the editor
• Macro argument substitutions in the body of a macro definition (e.g. ${argname}) are italicized
• Macro invocations (e.g. $MYMACRO(a, b,c) are colored violet
• TOON conditional branching expression operators (e.g. >=0) are colored red
• TOON IF and GOTO keywords, and the = assignment operator are colored red

Update Command Line Build Tools

You can modify the FXCore "assemble.cmd" script (part of the FXCore tools distribution) to run the macro processor as the first step. The lines that have been added or modified are noted in the comments:

abd in red

@rem passed order is: full_current_path current_directory name_part preproc_library_path assembler_directive assembler_directive
@echo off
rem if old .fxo exists delete it
IF EXIST "%~2\%~3.fxo" (
 del "%~2\%~3.fxo"
)

rem ADDED if old .fxo-mp exists delete it
-IF EXIST "%~2\%~3.fxo-mp" (
 del "%~2\%~3.fxo-mp"
)

rem ADDED Macro processor: reads .fxc and outputs .fxc-mp
java -jar "%~dp0FXCoreMP.jar" "%~2\%~3.fxc" "%~2\%~3.fxc-mp"
if not %errorlevel% EQU 0 (
	echo ERROR running macro processor
	color 4F
	pause
)

rem MODIFIED NEXT LINE run the preprocessor on the .fxc-mp file, outputs .fxo file
"%~dp0FXCorePreProc.exe" -l %4 %~2\%~3.fxc-mp
if not %errorlevel% EQU 0 (
	echo ERROR running preprocessor see %~3.fpl
	color 4F
	pause
) else (
	rem preprocessor ran fine now assemble the new .fxo file
	"%~dp0FXCoreCmdAsm.exe" %5 %6 -a "%~2\%~3.fxo"
	if %errorlevel% EQU 0 (
		echo. & echo NO ERRORS 
		pause
	) Else ( 
		echo. & echo ERROR FAILED &color 4F 
		pause
	)
)