MSXBUILD

Utils to use openMSX in build pipelines.

You can use these scripts as-is. the files in the lib are all you need.
But as always, feel free to extend it for your specific needs or contribute a fix or feature.

Features

• Allows parallel headless openMSX build pipeline
• openMSX safe exit failure guards
• Automatic disk image import + export per build step
• Downloads and caches resources from msxhub.com
• Auto magic openMSX extensions and machine rom's setup
• SDCC msx build steps
• Screenshot and/or video output of full build
• Embedded documentation of make options

Dependencies

• make + wget + tar + awk + grep + dos2unix
• sdcc
• openmsx
• ffmpeg
• rsync

For debian use;

apt-get install make wget tar gawk grep dos2unix sdcc openmsx ffmpeg rsync

Usage Classic

Have access or copy the lib folder in your project and start writing make files.

Include the lib/make/msxbuild.mk and override the paths if needed;

• PATH_SDCC=/usr/bin
• PATH_OPENMSX=/usr/bin

Usage Docker

TODO

Usage Help

Running: make

Welcome to the MSXBUILD help system.

For detailed fire help use one of the following targets;

 * @help-variable
        Lists build variables.

 * @help-variable-deep
        Lists deep variables.

 * @help-variable-rock
        Lists rock variables.

 * @help-variable-flow
        Lists flow variables.

 * @help-function
        Lists build functions.

 * @help-function-deep
        Lists deep functions.

 * @help-function-flow
        Lists flow functions.

 * @help-target
        Lists build targets.

 * @help-target-deep
        Lists deep targets.

 * @help-all
        Lists all documented information.

Example Project

When you want to see whats happening do a debug run;

normal run;
	time make bin/@assert-all
	real    0m3.223s

debug run at 11 Mhz;
	time VERBOSE=on MB_OPENMSX_HEADLESS=off MB_OPENMSX_THROTTLE=on make bin/@assert-all
	real    1m4.856s

debug run real msx speed;
	time VERBOSE=on MB_OPENMSX_HEADLESS=off MB_OPENMSX_THROTTLE=on MB_OPENMSX_SPEED=100 make bin/@assert-all
	real    2m37.379s

record run with screenshot on exit; (black screens without throttle)
	time MB_OPENMSX_HEADLESS=off MB_OPENMSX_THROTTLE=on MB_FLIGHT_SCREEN=on make bin/@assert-all
	real    1m14.043s

record run with video per session and merge to one video file;
	time MB_OPENMSX_HEADLESS=off MB_FLIGHT_VIDEO=on make bin/@assert-all
	real    0m7.136s

build parallel;
	time make -j4 bin/@assert-all
	real    0m1.817s

manual test msxhub on machine;
	make DIST_QA_MSXHUB_MACHINE=Philips_VG_8000 bin/dist-qa-msxhub/@run

Errata

• boot_exec_setcolor: does not work on MSX1 vdp TMS9918
• Doesn't work on windows
• TODO: mbboot80+add arg prefix and move to other repro + msxhub package
• TODO: Missing C and mixed support
• TODO: Use TCL for BASIC/ASM/C lcov (Cobertura) code coverage

OpenMSX backlog issues

• (FIXED:rm-SDL) Bug: screenshots sometimes segfaults when using SDL renderer
• Screenshots don't work without throttle
• (FIXED++) Audio device init option + warning messages on computer without sound card
• MIDI device init option + warning messages on computer without sound card
• Enhancing the IDE CD-ROM support
• Allow <type>IDEHD</type><DeviceName>OPENMSX IDEHD</DeviceName> now hardcoded in IDEHD.CC:37 + update default for mode 40
• Diskmanipulator export (sync) fully non-cased filename compare (duplicates)
• Diskmanipulator export (sync) don't touch/overwrite unmodified files
• Diskmanipulator reuse the device defined filename
• Diskmanipulator Imported folders in openMSX; cd utils;cd ..;dir breaks, use cd utils:cd a:\;dir as workaround
• run instance-id or run/process-label to replace hardcoded "untitled1" path
• Remove msg or add ignore sram-fully or blank setting: SRAM file nms8250.cmos not found, assuming blank SRAM content.
• Video record append mode + optional multiple previds to glue videos as one
• SDL-NULL as window less renderer so that screenshot and/or video works headless
• (FIXED:rm-SDL)Video record remove blue start frame on start of recording
• (FIXED++) Allow for set renderer none in TCL or command argument for headless mode
• (DONE) DocUpdate: Added optional exit code of exit command
• DocUpdate: Add speed note because it is slow + add example "after quit {export hdd}"
• DocUpdate: Wrap all TCL commands in catch+stderr+exit1
• DocUpdate: Add 'headless' example via stdio+new + link to control omsxctl

Make4++ backlog issues

• Add a few new define's to have official make documentation
• Add function call_real which exits on undefined call argument
• Add -e option to make internal echo command for escaped sequences
• Add native OS functions for os_copy,os_rmfile,rmdir,mkdir,touch,delfile,deldir
• Add string str_lenght function
• Add string str_is_ascii function (death with unicode)
• Add str_lowercase and str_uppercase functions (full 21bit unicode support)
• Add call_flow fail on undefined argument and puts result in eval to parse flow rules
• Add define_flow which reverses dollar escaping so write $$(1) for $(1) and other are like normal
• Add XML output for help system for integration with IDE's
• Add rwildcard for deeper searches
• Add namespace support for variables/functions/targets like: moduleX::bin/prog.o: moduleX::src/prog.c
• Add checksum function to calc checksum for file
• Add os_copy_diff function to use checksums to copy only changed files
• Allow make to use checksums not timestamps to detect file updates
• Define (binary) namespaced XML to replace ascii Makefile syntax
• Make5: Remove guile support fully (maybe replace with embedded MSX BASIC)
• Make5: Add converter command for upgrade make4 syntax and option to run make4 file.
• Make5: move all internal's to namespace's
• Make5: upgrade to new BDOS split file and folder API in OS kernel VFS layer
• Make5: Delete all Old-Fashioned Suffix Rules code
• Make5: Delete .EXPORT_ALL_VARIABLES and export without variable
• Make5: Delete VPATH search variable (replace with namespace vpath ??)
• Make5: Delete/refactor all (old) code that make the make code ugly
• Make5: Adds zillala (emacs like) bug reporting output for when make fails script or internally
• Make6: Only support 18bit four corner method, fixed i18n words, no letters, no ascii, no unicode