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.
