Building NitrOS9

Note: To build NitrOS-9 version 3.3.0 or older, use LWTOOLS 4.11. To build from hg repo use the latest LWTOOLS release.

The LWTOOLS and ToolShed utilities are used to build the NitrOS-9 operating system on Mac, Windows, or Linux based systems. If you would like to set up your system to build the project, please follow the instructions below.

Notes about spaces in directory paths

Directory/folder names with spaces in them will prevent the build scripts from working. This can happen on Windows if using OneDrive or Mac OS X if using iCloud Drive. Building out of a directory located in either will have spaces in the path name ("/Users/username/Library/Mobile Documents/com~apple~CloudDocs/" for example).

The error messages may be confusing. In this case, the space in "Mobile Documents" causes the build to fail, and the error reports it cannot find a directory called "Mobile":

make: *** /Users/username/Library/Mobile: No such file or directory.  Stop.
make: *** [all] Error 2

Move the source code to a path without spaces (outside of the shared folders). You can then build it there, or make a shortcut/link/alias to that location where you want it.

Notes for Linux platforms

For Debian/Ubuntu you can get prebuilt LWTOOLS and Toolshed from https://launchpad.net/~tormodvolden/+archive/m6809 Other packages needed are: mercurial, make, zip

Notes for Windows platforms

For Windows you can get prebuilt LWTOOLS from http://lwtools.projects.l-w.ca/contrib/tormod/ and prebuilt Toolshed from https://sourceforge.net/projects/toolshed/files/ToolShed/

Mercurial (hg) can be installed from http://mercurial.selenic.com/wiki/Download for instance by downloading the Mercurial MSI installer (ca 6 MB).

The build process must be done in a Cygwin or MingW environment.

On MingW you will have to append "CC=gcc" to the "make" lines below. See also Building NitrOS9 in Windows using Cygwin or Building NitrOS9 in Windows using MinGW for more Windows specific issues.

Obtain and build LWTOOLS

hg clone http://lwtools.projects.l-w.ca/hg/ lwtools
cd lwtools
make
make install
cd ..

This will build and install lwasm, lwlink, lwar and lwobjdump into your /usr/local/bin directory. If "make install" fails on unsufficient permissions, run "sudo make install".

Obtain and build the Toolshed tools

hg clone http://hg.code.sf.net/p/toolshed/code toolshed
cd toolshed
make -C build/unix install
cd ..

This will build and install the toolshed tools into your /usr/local/bin directory. On Linux/Mac OS X systems, if the build fails with an error similar to:

...
install -m 0644 doc/ToolShed.html /usr/local/share/toolshed
install: /usr/local/share/toolshed/ToolShed.html: Permission denied
make: *** [install] Error 71

...use "sudo make -C build/unix install" if needed.

Verify your build environment

Before trying to build NitrOS-9 verify that all above components are correctly installed:

• Typing lwasm -V should display the LWOOLS version
• Typing os9 should display the ToolShed version (and usage instructions)
• Typing hg --version should display the mercurial version

If a command above is not found, make sure that it is in your path, either by editing your shell startup scripts or by entering PATH=$PATH:/usr/local/bin in your active command shell.

Obtain and build NitrOS-9

The very first time you will need to clone the NitrOS-9 repository:

hg clone http://hg.code.sf.net/p/nitros9/code nitros9
cd nitros9

At this point you are ready to rock. To build all of NitrOS-9 including things you almost certainly don't want:

make dsk

Alternatively you can first change to the directory containing the system you would like to build, for instance:

export NITROS9DIR=$PWD
cd level2/coco3
make dsk

Or just stay in the top folder and specify a "port" (coco2, coco3, coco3_6309, etc):

make dsk PORTS=coco3

You should now find disk images have been created in the various directories. For instance, the boot disks for level 2, 6309 can be found in the level2/coco3_6309 subdirectory.

To find a list of available PORTS= targets, look in the makefile located in nitros9/level1, nitros9/level2 and nitros9/level3 for the line dirs = xxx xxx xxx. Those items are ports that can be built this way.

Updating your build

If you later want to update your NitrOS-9 build, pull the latest repository changes and update your tree, and build again. Change directories in to the nitros9 directory then fun these commands:

hg pull
hg update
make dsk

Updating an old repo clone (2013 or earlier)

At a point in development the "lwtools" branch was used, so if updating from a repo from that time, change directories in to the lwtools directory then run this command once to change your current branch to the "default" branch:

hg update default