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;

• MB_SDCC_PATH=/usr/bin
• MB_OPENMSX_PATH=/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 @package-qa
	real    0m8.058s

debug run at 11 Mhz;
	time VERBOSE=on DEBUG=on MB_OPENMSX_HEADLESS=off MB_OPENMSX_THROTTLE=on make @package-qa
	real    2m34.071s

debug run real msx speed;
	time VERBOSE=on DEBUG=on MB_OPENMSX_HEADLESS=off MB_OPENMSX_THROTTLE=on MB_OPENMSX_SPEED=100 make @package-qa
	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 @package-qa
	real    2m40.784s

record run with video per session and merge to one video file;
	time make @flight-video-package-qa
	real    0m18.184s

build parallel;
	time make -j4 @package-qa
	real    0m4.226s

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

view the make graph of an target;
	make -Bnd bin/dist-qa-msx1/@assert | make2graph | dot -Tpng -o /tmp/out.png;open /tmp/out.png

Errata

• Make: @@include-mods will not get chained, it doesn't list ANY dep anymore
• Make: @@include-tree will not get phony, (and thus @@include-root not on top)
• 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
• 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
• BUG: Unicode read+parse ok but function call fails on include $(MB__BASEPATH)/lib/make/प्रणालीᐥᔆʸᔆᐪᓫᔿ/mb_doc.mk.
• 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 letters function
• Add string isascii function (death with unicode)
• Add lowercase and uppercase functions (full 21bit unicode support)
• 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: Replace all ultra short 1980's magic templates variables with ultra long human readable name
• 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