The Haujobb Amiga Framework

Abstract
This document describes how to setup and use the Haujobb Amiga Framework on Amiga and PC. It guides you through setting up the required components in small steps with immediate incentives.
Source on GitHub: https://github.com/leifo/haujobb-amiga
Documentation at: http://www.dig-id.de/amiga/framework/
PDF at: http://www.dig-id.de/amiga/framework/haf.pdf
image: 0T__docs_haujobb.jpg


Table of Contents

Part I Overview and Setup
Part II Demomaking
Part III Annex

Part I Overview and Setup

The Haujobb Amiga Framework facilitates modern Amiga demo making on several levels.
On its lowest level, WickedOS, it provides with you with an API for assembly-level access to over 20 different chunky to planar based screenmodes, several music replayers, and interrupt hooks. You can choose from using a multi-tasking-friendly hardware abstraction layer, or a traditional multi-tasking-killer mode. WickedOS has been used in a number of our Amiga demos, ranging from Mnemonics to Beam Riders. By default it targets “todays” 68060 AGA demos, i.e. having an FPU and at least a 68020 or better CPU in the target machine.

1 Assembler and Linker Setup

Traditionally, many Amiga-demos were made using ASM-One, or one of its derivates. I have personally worked with ASM-One v1.29 for many years, and demos like Mnemonics were made almost exclusively with that assembler, while other parts relied on genam from the Devpac 3.04 package. To honor that tradition, WickedOS stays fully compatible with ASM-One and Devpac. But, more importantly, it can also be used with tools like vasm and vlink, both natively on the Amiga, and for cross-compiling on the PC.
This setup chapter will take you on a quick tour through the different components that are required to get you up and running step by step.
To get started, grab the release archive of our framework from GitHub at https://github.com/leifo/haujobb-amiga.

1.1 Includes from NDK

First of all, you need to have the assembler include-files available at “INCLUDES:”. WickedOS doesn't need the latest features of AmigaOS, so it is likely to work with the includes that you might already have. If not, do as follows.
Obtain a copy of the latest AmigaOS Native Developer Kit (NDK). At the time of writing this was version 3.9 and it was still available at www.haage-partner.de/download/AmigaOS/NDK39.lha
  1. Unpack the archive on your Amiga
  2. Assign “INCLUDES:” <whereYouUnpackedIt>/Include/include_i
  3. List includes:hardware/custom.i (should list a file, mine is 3045 bytes long)
  4. Consider putting the assign from line 2 into s:user-startup (optional, but you must provide the assign to INCLUDES: if you plan to assemble WickedOS on Amiga).

1.2 vasm and vlink

We can now use vasm to assemble the WickedOS source into a linkable binary object (.o) file, and then link that into an executable file using vlink. These portable command-line tools are at the core of our strategy for cross-development, together with vmake and vbcc, which will be covered later in this document.
The project homepages are at http://sun.hasenbraten.de/vasm/and
http://sun.hasenbraten.de/vlink/. You can get the binaries, sources, as well as complete documentation for both tools at their respective homepages.
The supplied WickedOS source assembles out of the box on Amiga and PC. The following sections show you how to do it.
To assembe on the Amiga, get the latest release binaries from
Copy the contained files vasmm68k_mot and vlink to your path (e.g. to “C:”). Confirm that they are working by typing:
The output version numbers should somehow match those that are mentioned on the project homepages. Note that vasm is not only portable, i.e. ready to make work on different plattforms, but also retargetable, i.e. able to assemble sources for different target CPUs with different syntax modules. Shortcodes for the latter two are automatically appended to the binary executable name. Although many different versions of vasm exist, we are only interested in the 68k_mot version. If you are like me and like shorter names, you can add “alias vasm vasmm68k_mot” to your s:user-startup to make your life a little bit easier once in a while.

1.3 Example: Wostest

With vasm and vlink in place, you can already assemble, link and execute the built-in example like this:
  1. cd WOS:
  2. execute buildwostest.bat
  3. wostest
This procedure should build and run an example screen. See the screenshot for a typical output of the shell and of wostest.
image: 1T__docs_wostest.png image: 2T__docs_hautjob.png
Figure 1.1: Wostest assembled on Amiga, output
vasm and vlink are called from buildwostest.bat, which contains only two lines. Let's look at them in more detail:
vasmm68k_mot -Fhunk -m68020 -m68882 wos_v1.63.s -o wostest.o
-Ic:/vbcc/NDK39/Include/include_i -DWTEST
vlink wostest.o -o wostest
The vasm-line specifies a number of things about our source and target binary via these parameters:
Finally, the vlink-line takes the output-file generated by vasm, wostest.o, and turns it into an executable file, wostest.

1.4 Assembling on PC

Windows binaries of vasm, vlink and make are shipped together with the vbcc-compiler which can be obtained from http://sun.hasenbraten.de/vbcc/
Download and run Install-VBCC.exe, as decribed elsewhere in more detail. Please skip to that page. Then come back and confirm that the tools are working by opening a command prompt and typing:
image: 3T__docs_wostest-pc.png
Figure 1.2: Wostest assembled on PC
With vasmm68k_mot and vlink in place, you can then just:
  1. cd <to the directory where you unpacked WickedOS on PC> (here: t:\wos)
  2. type “buildwostest.bat” to cross-assemble and link wostest on the PC
Note that the binary output produced on the PC is exactly the same as on the Amiga, of course. Also note that this worked in a fraction of the time that it took on the Amiga. Yes, it was really that fast. Welcome to Modern Amiga Demo Cross-Development!

1.5 Shared Folders between Amiga and PC

Now that you cross-compiled an Amiga executable blazingly fast on your PC, you wouldn't want to waste any time getting it onto your Amiga for testing it, would you? So manual file-copying via FTP, CF-cards, or by other means is not going to be fast enough for quick turn-around times. Your ideal setup depends on whether you want to work with emulated or real Amigas, or both.
Emulators
like WinUAE allow adding a folder from the host-computer as a volume on the emulated Amiga. Do yourself a favour and use this feature!
I personally mounted a volume “WIP:” (as in Work In Progress) from a folder that I mounted from a Network Attached Storage (NAS, a Synology here) on the PC. This is because...
Real Amigas
cannot just mount your Windows folders. NAS folders, on the other hand, are made to be mountable, and can also easily be mounted on Amigas that have:
PC-Ramdisks
are a fact. Yes, they do exist! Even though they are not shipped as part of the Windows operating system, like on Amiga, you can easily download and install very powerful third-party components. And PC-based Ramdisks are just as useful as they have always been on Amigas. This is what I did:
  1. Download and install ImDisk Virtual Disk Driver
  2. Configure a Drive Letter “T:” with a 2 GB RamDisk using File System “NTFS”
    1. check: “Allocate Memory Dynamically”, “Launch at Windows Startup”
    2. uncheck: “Create TEMP Folder”
  3. Mount that folder as “PCT:” in WinUAE (very useful for quick data exchange, esp. downloads)

2 Compiler Setup

When planning to develop Amiga software with the C programming language, there are a number of C-Compilers to choose from. Most notably they are:
As we were looking for a cross-compiling solution, SAS/C, Storm C and DICE were no options. They are also neither free and open source, nor actively maintained, which was our second selection-criteria. This left us to decide between GCC and vbcc. At the time when we made our decision in 2009/2010, the Amiga-port of GCC was lacking behind in version numbers, while vbcc was the relatively new thing that was used by several Amiga-coders, and personally recommended by Kalms of TBL. It also allows for writing inline-assembly in the familiar Motoral syntax, rather than the more alien GCC Assembler syntax.
Moreover, vbcc is designed to work in combination with vasm and vlink from the same authors. The maintainer of the Amiga bindings, Frank Wille, is one of the most experienced and longest standing developers of quality Amiga development tools, ranging back to at least 1991 (with his PhxAssand PxhLnk). This long-term experience and continued commitment ensures first class Amiga support.
Hence, we decided to use vbcc as our C-compiler. The vbcc project homepage is located at http://sun.hasenbraten.de/vbcc/. There you can get the binaries, targets, sources, and complete documentation.

2.1 vbcc setup on Amiga

Installation on Amiga is easy. Citing the vbcc download instructions:
You need to pick the appropriate binary archive for your host platform. Then you can add as many target archives as you need. [..] Install the binary archive first, using the provided Amiga installer, then add the targets.
So, download and install:
  1. AmigaOS 2.x/3.x 68020+ binaries
  2. Compiler target AmigaOS 2.x/3.x M680x0
The archives contain standard Amiga Installer scripts. Run them. Then test if the following commands are available:
  1. vc
  2. vbccm68k
The former is a frontend for the latter and is very handy, if you are planning to use the C-compiler on the Amiga..

2.2 vbcc setup on PC

Installation on PC is even easier. Basically, just download and install a single file from the vbcc homepage. But be aware that the download is falsely reported to be a infected by malware by several virus scanners! Therefore:
  1. Disable your virus-checker (optional)
  2. Download and install Install-VBCC.exe with these settings
    1. Leave “Default compiler target” as AmigaOS 2.0
    2. Change path (below) to C:\vbcc
    image: 4T__docs_install-vbcc.png
    Figure 2.1: VBCC Installer for Windows
  3. Enable your virus-checker again. If your were curious about this installer, you could:
    1. check the sources at GitHub
    2. follow the thread Windows installer for VBCC tool chain at the English Amiga Board
    3. or believe us that it is fine.
The good news is that you are already done! Open a new command prompt and test that the following commands are available:
  1. vc
  2. vbccm68k
  3. vasmm68k_mot
  4. vlink
  5. make

2.3 Example: Hello world

Let's compile our first C-source with this setup! The following procedure should work on the Amiga aas well as on the PC side.
  1. cd to the /examples/helloworld folder
  2. vc hello.c
    1. this should generate an Amiga executable “a.out”
    2. alternatively provide a filename with: vc hello.c -o hello
  3. Run the freshly compiled executable on Amiga.
For completeness, this is the full source of hello.c
/* hello world, noname, 23.10.18
compile with:
- "vc hello.c" (compiles to file a.out)
- or "vc +aos68k hello.c -o hello" (being more explicit about what we want)
- or "vc +aos68k hello.c -o hello -v" (to see commands as called by vc)
- or "make" (using makefile)
*/
#include <stdio.h>
int main(int argc, char **argv)
{
int i;
if (argc==1)
{
/* no args */
printf("Hello, world!\n"); /* argv[0] is always the filename */
printf("Called from filename: %s\n", argv[0]);
}else{
/* arguments given, start at argv[1] */
printf("Hello");
for (i=1; i<argc; i++)
{
printf(", %s",argv[i]);
}
printf("!\n");
}
return 0;
}
This is slightly extended hello world that also makes use of the provided arguments (i.e. argc and argv). You can also build the binary by executing build.bat. This example also comes with a simple makefile. But in order to build it from there, you first have to install make itself.

3 GNU make

While using batch-files for scripting repetetive tasks is useful, you are quickly hitting the roof with that approach. Which files need to be built, and how? This is where makefiles and make come into play. They coordinate the software build process in a structured way. Required tools, source-files, and libraries are listed in the makefile. Based on the rules that are also noted in the makefile, the make-tool then coordinates the build-process, i.e. turning source-code into an executable file.
We are using GNU make for building the Amiga target, as it is a free standard tool that is available on both Amiga and current plattforms. It is your choice to install it on Amiga and/or PC. The forthfollowing test should run on both platforms.

3.1 Configuring make on Amiga

  1. Get a native Amiga binary from: http://aminet.net/package/dev/c/make-3.75-bin and put it to your path
    1. Please note that the v3.75 from Aminet is in fact a v3.74 ported natively for Amiga. The author just bumped the version number for his efforts.
    2. Open a newshell and type “make -v” to check that make is working
      1. it should show you its version number.
      2. In case you get a stack overflow warning type “stack 20000” and try again

3.2 Configuring make on PC

  1. Make is bundled and installed with Install-VBCC.exe, as describedelsewhere (v4.2.90 at the time of writing). Thus you should have already installed it.
    1. This is the preferred version
    2. Alternatively, older Windows binaries can be obtained from:
      http://gnuwin32.sourceforge.net/packages/make.htm
  2. Open a command prompt and type “make -v” to check that it is working
    1. make should show you its version number.

3.3 Building the WickedOS C2P-converters

We are aiming to use make on both Amiga and PC. Test that it works for you in two steps:
  1. Use it to assemble a bunch of real world assembler files with a given makefile
    1. cd to /sub
    2. make
This should call vasm on about two dozen assembly-files from the /chunky subfolder and generate the same number of *.bin files. These files are the actual chunky to planar (C2P) converters for WickedOS' different screenmodes. If the distribution archive came only with one bin-file (for screenmode #1, as used in the initial example), you have now enabled the rest of them. Congratulations, well done!

3.4 Cleaning with rm

After work comes the clean-up! For make this is “make clean” which usually deletes a bunch of assembled or compiled binary object files and needs a delete command in order to work. Unfortunately, these delete commands differ between operating systems, not only by name, but also by syntax. In order to keep at least a somehow coherent structure, we define as per convention that a command “rm” should be reachable and work like rm from GNU coreutils.

3.4.1 On Amiga

Just add another line to s:user-startup: “alias rm delete”. Please note that this is not ideal but will work reasonably well for small projects, as long as the command-line does not get too long. Unfortunately, the command-line of the C2P-converter example with over 20 entries is already exceeding those limits. Mea culpa!

3.4.2 On PC

Windows del is not good enough for our purposes! Therefore we are using rm from GNU coreutils, a.k.a. fileutils.
  1. Get the latest binaries from
    http://gnuwin32.sourceforge.net/packages/coreutils.htm
    1. either choose the setup file, or just the binary.zip
  2. At your discretion, install all the tools, or just copy rm.exe from the bin-folder in the zip-file to your path
    1. it is suggested to copy rm to c:\vbcc\bin
    2. in case you choose the file from the zip-file, add missing dependencies from coreutils-dep-zip
  3. Open a command prompt and type “rm --help” to check if it is working
  4. Finally, try it in combination with make
    1. cd to the /sub directory again
    2. type “make” and it should tell you “Nothing to be done for `all'” which means that all assembled filed were up-to-date.
    3. type “make clean” to remove those files
    4. type “make” again and see it rebuild.
This concludes the setup of the Amiga-oriented tools.

4 PC-Prototyping Environment

A large part of the productivity-benefits of our toolchain stem from the use of a native PC-build while prototyping the effects and editing the demo. This takes cross-compilation out of the picture for a period of time and allows you to focus on getting something on screen, debugging it, and then making it look nice before focussing again on making it all run smoothly on the Amiga. It also allows you to exploit the PC-hardware that you own anyway for your own sanity, e.g. use your big monitor wisely and fill it with a modern IDE with syntax-coloring, code-completion, code-navigation, project support, and of course debugging facilities. And run all of this natively on your modern multi-core CPU to save time and keep you in the flow.
For this to work you need a compiler, an IDE, and a debugger. While in theory these components would all be included in the popular Microsoft Visual Studio, we have blended it in our toolchain with QtCreator as the IDE component. While this was mainly a simple personal preference for a nice IDE that can work with different compilers, it also kept our toolchain itself plattform independant! QtCreator is available for Windows, macOS, and Linux. For the latter two, you would be able to set it up with gcc. For Windows, you best use it in combination with Microsoft's compiler.

4.1 Visual Studio

Let's start with installing Microsoft Visual Studio (MSVC), which comes in many different versions over the years (see table). The oldest one that we have personally tested is 2010. If you already have Visual Studio installed in a least that version, you can skip this section.
Visual Studio
2010
2012
2013
2015
2017
Pro
OK
not tested
OK
not tested
not tested
Community
-
-
not tested
OK
OK
Table 1: Supported Microsoft Visual Studio versions
While Visual Studio was, and still is, a full-price commercial product, Microsoft has launched a number of free (as in beer) editions over the years. The Express edition introduced in 2005 has long since been discontinued and is now superseded by the Community edition. Visual Studio Community 2017 will work well for us. Please download it from https://visualstudio.microsoft.com and then install it on your Windows machine.
With Visual Studio Community 2017, please also install the missing standard headers by selecting Windows Universal CRT SDK under Individual Components -> Compiler, Buildtools and Runtimes, as described (6.1).

4.2 Qt Creator

Now let't install Qt and Qt Creator. The Haujobb Amiga Framework is known to work with Qt4 and Visual Studio 2010 as the minimum supported versions. If you haven't got Qt installed already, head over to https://www.qt.io/download, get the Open Source edition installer for Qt5, and run it.
It features many different options, we don't need all of them. Just install the latest available Qt 5.x.y release, as well as QtCreator and CDB support from the tools section (see figure 4.1).
image: 5T__docs_qt5-setup.png
Figure 4.1: Required Components from Qt Open Source Installer
Please note that the version numbers in the figure will change quickly and are already outdated at the time of writing. The figure also shows a setup wizard that was run on a machine with MSVC 2015 32-bit. You will need to pick the version that fits your installed compiler. It is your choice, to install 32-bit or 64-bit version (if available). The default path for installation if C:\Qt.
The official documentation for Qt Creator is at http://doc.qt.io/qtcreator/.

4.3 Debugger (CDB)

If you want to debug your C-programs in Qt Creator, you need to setup the CDB debugger. The official documentation for this is here. It boils down to downloading the Windows SDK from https://developer.microsoft.com/de-de/windows/downloads/windows-10-sdk. Then run the installer and uncheck everything except “Debugging Tools for Windows” (see figure 4.2).
image: 6T__docs_winsdk-debugger.png
Figure 4.2: Debugging Tools for Windows from Windows SDK

4.4 Kit Setup

In Qt Creator, combinations of compiler, debugger, Qt version, and a few other things are called a kit.
We need such a kit in order to work with our supplied project files (stars.pro, etc.). The full Qt doc for this is at http://doc.qt.io/qtcreator/creator-configuring-projects.html.
image: 7T__docs_qtcreator-debug-compile.png image: 8T__docs_qtcreator-kits.png
Figure 4.3: Compiler-, Debugger-, and Kit-Settings in Qt Creator 4.7
When you installed compiler, debugger and Qt as described above, go to menu Tools->Options. The presented options windows should resemble figure 4.3 (note that it has been taken with an older Windows SDK installed).
Select Kits on the left pane. Then:

4.5 Add-Ons

This section contains a few useful add-ons. Install them at your own discretion.

4.5.1 Syntax Highlighting for M68000 Assembly

This is really handy if you often work with M68000 assembly files in Qt Creator. Get asm-m68k.xml and install it. The documentation of Generic Highlighting in Qt Creator, as described in http://doc.qt.io/qtcreator/creator-highlighting.html should serve you as a basis. On my machine, I just copied the file to the Fallback Location (here: C:\QtSdk\Tools\QtCreator\share\qtcreator\generic-highlighter).

4.5.2 Qt Plug-In for Visual Studio

If you'd like to use our supplied Qt Creator Project files (*.pro) from within Visual Studio, you can install the Qt Visual Studio Tools as described in this blog-postand provided here(for 2015) and here(for 2017). You can also install it via the marketplace of Visual Studio.
Once installed:
  1. Select menu Qt VS Tools-> Qt Options
    1. add your Qt version
      1. the name is automatically provided
      2. just select the path that leads to /bin/qmake under c:\Qt
      3. this only works for Qt5 and up
  2. Select menu Qt VS Tools->Open Qt Project File (.pro)...
  3. Build & Run
Please note that our IDE of choice is Qt Creator, so if you run into problems with Visual Studio, we would be more happy to hear about your solutions, and less prepared to help you fix it.

4.5.3 Symbol Files

Even though you have already installed a lot of data, the symbol files have not been part of it. They would usually be loaded on demand over the Internet connection and then cached locally. If you want to prepare yourself for longer times without Internet, get the symbol files. You can read more about this topic in this article. We also have a direct download link somewhere and will add it here at some point.

4.6 Summary (TL;DR)

The Haujobb Amiga Framework supports development of Amiga demos on PC, and then cross-compiling them for the Amiga.You probably didn't want to compile and assemble on the Amiga anyway, so you just:
This is all that needed to be done, so you could now open our supplied example project files (*.pro) in the /demo folder and start making Amiga demos on PC.
Enjoy!

Part II Demomaking

5 Examples

This chapter takes you through the provided examples in order of complexity.

5.1 Hello World

Let's start with a simple hello world. We just want to build and run it from within Qt Creator to confirm that everything works.

5.1.1 Overview

You should be presented with a console window and some printed text.

5.1.2 Discussion

It couldn't get much simpler than this. Basically, just a couple of printf()'s, which require stdio.h. If compilation fails for you on that header file, solve the issue now, as described elsewhere.
The example also shows the use of parameters that are provided to int main(int argc, char **argv), with argc being the argument count, argv[0] the filename, and argv[1..n] the supplied arguments, if argc>1.
Finally, the project also showcases the need for a shadow-build-subdirectory (such as /build), as Qt Creator calls qmake which creates its own “makefile”-file and thereby overwrites our existing “makefile” in GNU make syntax (6.1), which we need to build for Amiga. All further examples will thus employ a /build folder for the Amiga-specific build files.

5.2 Stars

Just a classic star-field.

5.2.1 Overview

You should be presented with a graphics window and some shaded 3D stars flying towards you, as show in figure 5.1.
image: 9T__docs_qtc-stars.png
Figure 5.1: Qt Creator session with project stars

5.2.2 Discussion

This example does not load any external files. The starfield is set up and drawn from a seperate file called starseffect.c (with fitting header starseffect.h) which is then called from main.c. Keeping the effect-code seperated like this is good practice and will become very useful once we start putting together a demo.
Let's study the code in figure 5.1starting from main():
The resulting effect is a classic, albeit simple starfield. It doesn't rotate or even just move in different directions. All of this could be added, if needs be. But we recommend you to go on and just take this as an example of a typical project setup.

5.2.3 Compile for and run on Amiga

If you now wanted to compile the stars for Amiga, you would:
And then to run it on the Amiga, you would:
For this simple project, which doesn't load any external data-files, you could actually also run it from the build folder. But as soon as you want to load data (which we put in /data by convention), you would need to make sure you run your executables from the right folder.

5.3 Pictures

5.4 Movetable

5.5 Hello Demo

5.6 More Examples


Part III Annex

6 Trouble-Shooting

6.1 Missing Standard Headers

With Visual Studio Community 2017 we have witnessed missing standard headers, resulting in compilation problems even for the simplest programs such as the hello world (5.1).Unbelievable as it sounds, this behavior is also documented on Stack Overflow, along with the solution in answer #1.
To solve this problem, you need to rerun the Visual Studio Installer and select Windows Universal CRT SDK under Individual Components -> Compiler, Buildtools and Runtimes. Then restart you IDE, and rebuild your project.

7 WickedOS

This is a collection of notes about the WickedOS-layer of our Amiga Framework. Normally, you should not need to study this, but you are very welcome to.

7.1 Built-In Test

If you are feeling nostalgic or curious, you can assembly and run a built-in example of WickedOS in ASM-One or Devpac on the Amiga! The visual outcome will be the same as that described in section 1.3.Of course, it doesn't matter if you are using real or emulated hardware for this.

7.1.1 With ASM-One

If you coded on Amiga before, chances are that ASM-One is already installed and that you know how to use it. The minimum supported version is 1.29. If you do not have at least this one, just either:
Set the WOS: Assign before you start ASM-One.
  1. assign “WOS:” to where you unpacked WickedOS
  2. list WOS:wos_v#? (should list the main file, currently v1.62)
  3. Consider putting the assign from line 1 into s:user-startup (optional)
Then test WickedOS' built-in example AGA-screen from within ASM-One.
  1. Start ASM-One from a Shell (This is important, as starting it from an icon will cause you a lot of trouble, as previously discussed on Amiga Demoscene Archive.)
  2. Give it some public memory
    1. ALLOCATE Fast/Chip/Publ/Abs>p
    2. WORKSPACE (Max. XXXXX) KB>1000
    3. Note: ASM-One from Aminet (v1.48) seems to expect an assign “Sources:” at startup. If you don't have it, either:
      1. assign “Sources:” to somewhere useful, or just to “Ram:” for testing
      2. or in Asm-One go to Preferences->Environment and change “Default Dir:” textbox value to an existing directory or empty it
      3. or restart Asm-One with “!” to get the memory prompts again.
  3. Menu->Assembler->Preferences->Assembler
    1. CPU 68020
    2. Check “FPU Present”
    3. Uncheck “UCase = LCase”
    4. Uncheck “; Comment”
    5. Press “Save”
  4. Type “v wos:” (to set the working dir)
    1. v (to list the dir, just to confirm and refresh your memory)
  5. Type “r” (read) and select the latest version of wos:wos_v#?.s
  6. Press <ESC> to get into edit-mode
    1. Remove the “;” before WTEST in line 3
    2. Press <ESC> again to go back into command line mode (“>”)
  7. Type “a” (assemble), and ASM-One will assemble your source.
  8. Type “j” (jump), and you should see a nice picture and listening to a tune. (If it didn't work, you might not have AGA, 68020+ and FPU in your machine. Please note that WickedOS does not strictly require neither AGA nor an FPU, but this configuration is the baseline for the AGA/060 demos that we want to build with it.)

7.1.2 With Devpac

Devpac was probably the best allround commercial assembler development package for the Amiga. If you want to give it a go, either use your existing installation or get a copy from the English Amiga Board file server (files “Devpac v3.04#?.adf” in /Commodore_Amiga/App/Disk/).
Once installed:
  1. Project->Load the WickedOS main-file wos_v1.#?.s
  2. Remove the “;” before WTEST in line 3
  3. Settings->Assembler->Options
    1. Processor: 68020
    2. Check “68881/2 Maths Coprocessor”
  4. Program->Assemble
  5. Program->Run
Check the manual to learn about hotkeys, and the really powerful debugger “monam”. The manual is available at https://computerarchive.org/, which host lots of other Amiga manuals, too, in /files/comp/applications/amiga/manual.

7.1.3 Recap

You tested that the supplied WickedOS-sources directly assemble and work on the minimum supported assembler, ASM-One (without using intermediate object-files and linking). This provides the ground for the following steps with vasm and vlink.
If you were planning to make extensive use of WickedOS with ASM-One or Devpac on Amiga, you might be interested in setting the WOSASSIGN-flag. This would allow you to set your working directory to somewhere else and then just include WickedOS from wos:newestwos.s, which would then find all of its files from the WOS: assign.
But even if you don't plan to use ASM-One, you must at least provide the assign to INCLUDES: if you plan to assemble WickedOS on Amiga.

7.2 How to add a new screenmode

Adding a new C2P-based screenmode to WickedOS requires a few modifications at several places in several files. As I tend to forget at least one place for myself, this write-up is at least for my own reference.
Hint: you can set wtest flag in the main wos_v#?.s source for setup and display a simple screen. Note: XY is to be replaced with a running number, e.g. 19

in file wos#?.s

  1. in _wosbase:
    1. mXY: dc.l 0,0,0,0 ; add some comments as well
  2. in WOSInit:
    1. add an init block for your c2p-mode after the last one (.m18ok at the time of writing)
    ifnd NOMODEXY
    lea mXYc2p,a0
    lea mXY,a1 ;dc.l 0,0,0
    move.l a0,(a1)+ ;Init
    add.l #4,a0
    move.l a0,(a1)+ ;Main
    add.l #4,a0
    move.l a0,(a1)+ ;Exit
    endc .m7ok:; feel free to add custom init code here
    ; e.g. generation of ham masks or the like
  3. in _Display:
    1. add macro-line "_DisplayM1 XY" in first block
    2. add macro-line "_DisplayM2 XY" in second block
  4. in _RefreshDisplay:
    1. "add cmp.b #XY,d0" and "beq .mXY"
    2. provide fitting code at .mXY (copy from appropriate 8 bit or ham-based examples above)
  5. in SetModeAndColors:
    1. add macro-line "_SetMaCM1 XY" in first block
    2. add macro-line "_SetMaCM2 XY" in second block
    3. (for ham-modes) add special cmp/beq cases at ".m0"
  6. in _SetMode:
    1. add macro-line "_CallSetModeMac XY" in first block
    2. add macro-line "_SetModeMac XY" in second block
  7. in _SetColors:
    1. add macro-line "_SetColM1 XY" in first block
    2. add macro-line "_SetColM2 XY" in second block
  8. in Modes:
    1. provide fitting block which adds exactly one bit to MODES (double the number of the previous) e.g.
      ifnd NOMODE18
      MODES set MODES!131072
      endc
      1. (this bitwise-logic is why there are currently a maximum of 32 modes supported)
    2. include you binary code and provide label mXYc2p
      1. (code is expected to have jump table like all the other modes - init at 0, c2p at 4, etc..)

in file sub/wos_defines.i

  1. in struct after "Define the structure" comment
    1. add four rs.l 1 entries to structure for modeXYinit, modeXYc2p, modeXYexit, modeXYptr
  2. after "Set up the screen-dimensions" comment
    1. provide fitting MakeMode line to describe your screen dimensions
    2. (or alternative definitions of modeXYsize .. modeXYsize)

in file sub/wos_copperlists_v#?.s

  1. at EOF
    1. provide fitting copperlist named CopmXY, also with labels sprmXY and colmXY with appropriate space

in dir sub/chunky/sources

  1. Finally you need to provide a fitting c2p-routine as a PC-relative plugin. Check the provide sources and do likewise.
    1. name the file as "mode#?.s"

in file sub/chunky/sources/makefile

  1. add filename to Sources

8 Schematic Overview

image: 10T__docs_amiga-toolchain-graph.png