Olivers Guide To Compiling Contiki For Your C-64


Guide to building the 'Contiki for Retrocomputing' applications on your own

Introduction

This is a step-by-step guide to building the 'Contiki for Retro-computing' applications from the source code on Windows.

As things tend to change over time the question is if such a guide should be very specific and or more generic. This guide however is both including sections starting with ‘In general…’ and sections starting with 'At the time of writing…’.

Most Windows savvy people don’t like installation programs as those often do unwanted changes to the system and/or come with incomplete uninstalling programs – if there’s one at all. Therefore this guide successfully avoids installation programs. Rather all files are manually put into a single folder. Thus removing this single folder is all to be done for a residue-free uninstallers.

For the sake of simplicity of the remainder of this guide presumes a fixed location of this single folder so create now the folder c:\contiki.


 

The source

For building Contiki from the source code one obviously needs the actual source code.

In general the Contiki home page contains a link to the latest Contiki release:

http://www.sics.se/contiki/

At the time of writing the latest release is 2.5:

http://sourceforge.net/projects/contiki/files/Contiki/Contiki%202.5/contiki-2.5.zip/download

Expand the content of the .zip file including its top folder to the folder c:\contiki so that you end up with a folder c:\contiki\contiki-2.5.


 

The compiler

The primary tool for building applications from source code is the compiler. 'Contiki for Retro-computing' requires the cc65 compiler. This is a so-called cross compiler meaning that the compiler runs on one type of system (called the host system) producing programs for another system (called the target system). As cc65 supports both several host and several target systems the download is organized in a modular way allowing you to download only support for the systems you actually need.

In general the cc65 home page contains a link to the latest cc65 release:

http://www.cc65.org/

At the time of writing the latest release is 2.13.2.

Support for the host system Windows:

ftp://ftp.musoftware.de/pub/uz/cc65/cc65-win32-2.13.2-1.zip

Support for the target system Apple II:

ftp://ftp.musoftware.de/pub/uz/cc65/cc65-apple2enh-2.13.2-1.zip

Support for the target system C64:

ftp://ftp.musoftware.de/pub/uz/cc65/cc65-c64-2.13.2-1.zip

Support for the target system C128

ftp://ftp.musoftware.de/pub/uz/cc65/cc65-c128-2.13.2-1.zip

Support for the target system 8-bit Atari:

ftp://ftp.musoftware.de/pub/uz/cc65/cc65-atari-2.13.2-1.zip

Create the folder c:\contiki\cc65 and expand the contents of all the .zip files including their top folders to that folder. Test the correct operation by checking the folder c:\contiki\cc65\lib to contain four .lib files and the folder c:\contiki\cc65\bin to contain (among others) cc65.exe.


 

The build tools

Every somewhat more complex program is built using a build tool designated for that purpose. The primary purpose is to allow for a so-called incremental build, meaning that after a small change in the source code only those build actions are triggered which are actually necessary to be repeated to reflect the change in the final program.

The Contiki build system uses the program ‘make’ for that purpose. The program-specific description of what the generic ‘make’ is supposed to do is contained in so-called Makefiles. Those Makefiles contain (among others) calls to the compiler. However they contain as well calls to other program i.e. for creating folders, copying files etc. There’s a defined set of such program which every Makefile is allowed to just presume to be always available. Those programs are in fact always available on Unix-like systems but not on Windows so it is necessary to supply them. Fortunately the Contiki Makefiles call only very few such programs.

The usual way to have Makefiles work on Windows is to install the Cygwin environment. But this is a quite heavyweight and complex approach, which causes additional issues because the cc65 compiler to be called by the Makefiles is no Cygwin program but a so-called native Windows program. Therefore this guide instead describes how to have the Contiki Makefiles work in the native Windows Command Prompt by supplying just the minimal subset of programs to do so.

There are several projects providing native Windows versions of the programs in question. However the GnuWin project is the only one providing usable ones for free.

In general the GnuWin home page contains links to both the ‘make’ program itself as well as to the programs called by the Contiki Makefiles, consisting of the program ‘sed’ and the programs ‘cp’ and ‘rm’ which are part of the so-called Coreutils:

http://gnuwin32.sourceforge.net/

There are separate downloads for the programs themselves and their dependencies – meaning the .dll files they need. At the time of writing the dependencies of the program ‘sed’ happen to both contain all .dll files needed and the most recent versions of those .dll files:

http://gnuwin32.sourceforge.net/downlinks/sed-dep-zip.php

Create the folder c:\contiki\gnuwin32. Expand the folder ‘bin’ of the .zip file and its content to that folder.

http://gnuwin32.sourceforge.net/downlinks/sed-bin-zip.php

Expand the file sed.exe from folder ‘bin’ of the .zip file to the folder c:\contiki\gnuwin32\bin.

http://gnuwin32.sourceforge.net/downlinks/make-bin-zip.php

Expand the file make.exe from the folder ‘bin’ of the .zip file the to folder c:\contiki\gnuwin32\bin.

http://gnuwin32.sourceforge.net/downlinks/coreutils-bin-zip.php

Expand the files cp.exe and rm.exe from the folder ‘bin’ of the .zip file to the folder c:\contiki\gnuwin32\bin.

Test the correct operations by checking the folder c:\contiki\gnuwin32\bin to contain three .dll files and four .exe files.


 

The disks

Building the programs on a host system (in contrast to building them right on the target system) gets especially effective if there’s a target system emulator available for that host system. This setup allows for very quick turnaround times. But those emulators typically don’t work with individual files on the host system. Rather they require a single disk image file on the host system which represents a floppy disk for the emulated target system. The Contiki Makefiles allow creating those disk image files as part of the application build process. However the different emulators for the different supported target systems require different programs to be available for the actual disk image creation.

For the target system Apple II the program AppleCommander needs to be available. AppleCommander is a Java program meaning that a so-called JRE (Java Runtime Environment) needs to be installed on the host system. On most Windows systems this is already the case. This can be checked by executing java -version at a Windows Command Prompt. The command should report at least the Java version 1.3.x. Otherwise a (more recent) JRE needs to be installed from http://www.java.com/.

In general the AppleCommander home page contains a link to the latest AppleCommander release:

http://applecommander.sourceforge.net/

At the time of writing the latest release is 1.3.5:

http://downloads.sourceforge.net/project/applecommander/applecommander/AppleCommander%201.3.5/AppleCommander-1.3.5-ac.jar

Create the folder c:\contiki\ac. Copy the .jar file to that folder.

For the target systems C64 and C128 the program C1541 which comes with the emulator VICE needs to be available.

In general the VICE home page contains a link to the latest VICE release:

http://www.viceteam.org/

At the time of writing the latest release is 2.2:

http://www.zimmers.net/anonftp/pub/cbm/crossplatform/emulators/VICE/WinVICE-2.2-x86.zip

Expand the content of the .zip file including its top folder to the folder c:\contiki so that you end up with a folder c:\contiki\WinVICE-2.2-x86.

For the target system 8-bit Atari the program ‘dir2atr’ which comes with the AtariSIO package needs to be available.

In general HiassofT's Atari home page contains a link to the latest AtariSIO release:

http://www.horus.com/~hias/atari/

At the time of writing the latest release is 2010-10-02:

http://www.horus.com/~hias/atari/atarisio/tools-win32-101002.zip

Create the folder c:\contiki\atarisio. Expand the file dir2atr.exe from the .zip file to that folder.


 

The Contiki configuration file

The Contiki Makefiles add a contiki.cfg to a disk image file they create. In order to allow the application in the disk image to communicate properly that contiki.cfg needs to reflect the target system Ethernet device present (or emulated) and the target system TCP/IP settings to be used.

The Contiki download page allows adjusting all necessary settings and then downloading a ‘Configuration File Only’:

http://contiki.cbm8bit.com/

For the target system Apple II save the configuration file as:

c:\contiki\contiki-2.5\tools\apple2enh\sample.cfg

For the target system C64 save the configuration file as:

c:\contiki\contiki-2.5\tools\c64\sample.cfg

For the target system C128 save the configuration file as:

c:\contiki\contiki-2.5\tools\c128\sample.cfg

For the target system 8-bit Atari save the configuration file as:

c:\contiki\contiki-2.5\tools\atari\sample.cfg


 

The environment

The Contiki Makefiles require several specific environment variables to be set. The best way to do so is to create a small Windows Command Script file with the following content (using i.e. Notepad):

set CONTIKI=c:\contiki\contiki-2.5
set CC65_HOME=c:\contiki\cc65
set PATH=c:\contiki\cc65\bin;c:\contiki\gnuwin32\bin;%PATH%
set AC=c:\contiki\ac\AppleCommander-1.3.5-ac.jar
set C1541=c:\contiki\WinVICE-2.2-x86\c1541
set DIR2ATR=c:\contiki\atarisio\dir2atr

Save the .cmd file as c:\contiki\init.cmd.


 

The actual build

Now that all one time preparations are done the actual build can be performed :-)

Open a Windows Command Prompt in the folder c:\contiki and execute init. The build output contains various warning messages, but as long as the build continues and finally produces a disk image file there's no need to be concerned. The same is true for failure messages regarding opencbm.dll.

To build the the 'Contiki for Retrocomputing' applications for the target system Apple II execute the commands below:

make -C contiki-2.5/cpu/6502/dhcp disk TARGET=apple2enh

This command creates the file c:\contiki\contiki-2.5\cpu\6502\dhcp\contiki.dsk.

make -C contiki-2.5/examples/webserver disk TARGET=apple2enh HTTPD-CFS=1

This command creates the file c:\contiki\contiki-2.5\examples\webserver\contiki.dsk.

make -C contiki-2.5/examples/webbrowser disk TARGET=apple2enh

This command creates the file c:\contiki\contiki-2.5\examples\webbrowser\contiki.dsk.

make -C contiki-2.5/examples/wget disk TARGET=apple2enh

This command creates the file c:\contiki\contiki-2.5\examples\wget\contiki.dsk.

make -C contiki-2.5/examples/irc disk TARGET=apple2enh

This command creates the file c:\contiki\contiki-2.5\examples\irc\contiki.dsk.

make -C contiki-2.5/examples/email disk TARGET=apple2enh

This command creates the file c:\contiki\contiki-2.5\examples\email\contiki.dsk.

make -C contiki-2.5/examples/ftp disk TARGET=apple2enh

This command creates the file c:\contiki\contiki-2.5\examples\ftp\contiki.dsk.

To build the the 'Contiki for Retrocomputing' applications for the target system C64 execute the commands below:

make -C contiki-2.5/cpu/6502/dhcp disk TARGET=c64

This command creates the file c:\contiki\contiki-2.5\cpu\6502\dhcp\contiki.d64.

make -C contiki-2.5/examples/webserver disk TARGET=c64 HTTPD-CFS=1

This command creates the file c:\contiki\contiki-2.5\examples\webserver\contiki.d64.

make -C contiki-2.5/examples/webbrowser disk TARGET=c64

This command creates the file c:\contiki\contiki-2.5\examples\webbrowser\contiki.d64.

make -C contiki-2.5/examples/wget disk TARGET=c64

This command creates the file c:\contiki\contiki-2.5\examples\wget\contiki.d64.

make -C contiki-2.5/examples/irc disk TARGET=c64

This command creates the file c:\contiki\contiki-2.5\examples\irc\contiki.d64.

make -C contiki-2.5/examples/email disk TARGET=c64

This command creates the file c:\contiki\contiki-2.5\examples\email\contiki.d64.

make -C contiki-2.5/examples/ftp disk TARGET=c64

This command creates the file c:\contiki\contiki-2.5\examples\ftp\contiki.d64.

To build the the 'Contiki for Retrocomputing' applications for the target system C128 execute the commands below:

make -C contiki-2.5/cpu/6502/dhcp disk TARGET=c128

This command creates the file c:\contiki\contiki-2.5\cpu\6502\dhcp\contiki.d71.

make -C contiki-2.5/examples/webserver disk TARGET=c128 HTTPD-CFS=1

This command creates the file c:\contiki\contiki-2.5\examples\webserver\contiki.d71.

make -C contiki-2.5/examples/webbrowser disk TARGET=c128

This command creates the file c:\contiki\contiki-2.5\examples\webbrowser\contiki.d71.

make -C contiki-2.5/examples/wget disk TARGET=c128

This command creates the file c:\contiki\contiki-2.5\examples\wget\contiki.d71.

make -C contiki-2.5/examples/irc disk TARGET=c128

This command creates the file c:\contiki\contiki-2.5\examples\irc\contiki.d71.

make -C contiki-2.5/examples/email disk TARGET=c128

This command creates the file c:\contiki\contiki-2.5\examples\email\contiki.d71.

make -C contiki-2.5/examples/ftp disk TARGET=c128

This command creates the file c:\contiki\contiki-2.5\examples\ftp\contiki.d71.

To build the the 'Contiki for Retrocomputing' applications for the target system 8-bit Atari execute the commands below:

make -C contiki-2.5/cpu/6502/dhcp disk TARGET=atari

This command creates the file c:\contiki\contiki-2.5\cpu\6502\dhcp\contiki.atr.

make -C contiki-2.5/examples/webserver disk TARGET=atari HTTPD-CFS=1

This command creates the file c:\contiki\contiki-2.5\examples\webserver\contiki.atr.

make -C contiki-2.5/examples/webbrowser disk TARGET=atari

This command creates the file c:\contiki\contiki-2.5\examples\webbrowser\contiki.atr.

make -C contiki-2.5/examples/wget disk TARGET=atari

This command creates the file c:\contiki\contiki-2.5\examples\wget\contiki.atr.

make -C contiki-2.5/examples/irc disk TARGET=atari

This command creates the file c:\contiki\contiki-2.5\examples\irc\contiki.atr.

make -C contiki-2.5/examples/email disk TARGET=atari

This command creates the file c:\contiki\contiki-2.5\examples\email\contiki.atr.

make -C contiki-2.5/examples/ftp disk TARGET=atari

This command creates the file c:\contiki\contiki-2.5\examples\ftp\contiki.atr.


 

The outlook

The Contiki source files all come with Unix (LF-only) line endings. If you have no suitable IDE available you can edit them using WordPad. It doesn’t hurt that WordPad saves all modified files with Windows (CR-LF) line endings.

You can test the incremental build by (temporarily) changing the source file:

c:\contiki\contiki-2.5\apps\webserver\httpd-cfs.c

Change the port the web server listens on from 80 to 6502:

 tcp_listen(UIP_HTONS(80));

After the modification the line looks like this:

 tcp_listen(UIP_HTONS(6502));

Now execute again the command:

make -C contiki-2.5/examples/webserver disk TARGET=c64 HTTPD-CFS=1

After only a few seconds the .d64 file containing the modified web server gets created.

You can create you own 'Contiki for Retrocomputing' application using the examples as a starting point. In example create the folder c:\contiki\myget and copy the following files to that folder:

c:\contiki\contiki-2.5\examples\wget\wget.c

c:\contiki\contiki-2.5\examples\wget\Makefile

c:\contiki\contiki-2.5\examples\wget\Makefile.apple2enh.defines

c:\contiki\contiki-2.5\examples\wget\Makefile.atari.defines

c:\contiki\contiki-2.5\examples\wget\Makefile.c128.defines

c:\contiki\contiki-2.5\examples\wget\Makefile.c64.defines

Now remove the following line from the Makefile:

CONTIKI = ../..

Finally execute the command:

make -C myget disk TARGET=c64

This command creates the file c:\contiki\myget\contiki.d64.