# 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

* 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:SDL is removed) Bug: screenshots sometimes segfaults when using SDL renderer
* Bug: screenshots don't work without throttle
* Bug: Imported folders in openMSX; `cd utils;cd ..;dir` breaks, use `cd utils:cd a:\;dir` as workaround
* (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
* Command setcolor does not work on MSX1 vdp TMS9918
* Diskmanipulator export (sync) fully non-cased filename compare (duplicates)
* Diskmanipulator export (sync) don't touch/overwrite unmodified files
* Diskmanipulator reuse the device defined filename
* 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
* Video record remove blue start frame on start of recording
* (FIXED) Allow for `set renderer none` in TCL or command argument for headless mode
* SDL-NULL as window less renderer so that screenshot and/or video works headless
* 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