Thursday, January 7, 2016

RC 2016/01: My development tools, part 1

In my first blog of this retrochallange, prior to the start of the actual challenge itself, I talked about what tools I'll be using to develop kBase for the Apple IIe/IIc platform.  I haven't actually started coding my challenge yet, as this has been a busy week.  I'm hoping I'll be able to start this weekend.

I have done a "practice" project (discussed in my prior post) to refine my dev tool chain and tackle some technical issues.  With that accomplished, I wanted to take some time to discuss my development tools in more detail, so that people who were interested in C development for the Apple II might have a bit of a head start.  Or at least they could look at my project and know what NOT to do... :)

This is the first of two posts on this topic.  Here I'll discuss cc65 and AppleCommander.  In the next, I'll talk about my build tool, editor, and the emulators I'll be using.

First, a quick note about my development platform: I will be primarily working in Mac OS, so my tools will need to be Mac compatible.  However, I will at times be working in Windows as well, so I will need tools that are either cross-platform or platform-specific equivalents.  As it turned out, pretty much everything I use is available for both platforms, with the exception of the emulator I use for testing.  But there are good emulators for Apple II available on both Windows and the Mac, so that wasn't an issue.


The first major thing to discuss is the C compiler I'll be using, cc65.  This tool, which includes a C compiler, assembler, and a linker, runs on most modern operating systems.  I personally use it on both Mac OS X and Windows, and it will build on Linux and pretty much any Unix machine out of the box.  For Windows and Linux, this Getting Started page will tell you what to do.  For Mac OS X, it's essentially the same, but there is an additional step if you haven't already installed Apple's dev tools, as discussed here.  No matter your OS, it's really pretty simple to get cc65 installed and working.

I'm still learning my way around cc65.  It is has a lot of features, so despite my having done several small projects in it, I still feel like I don't know it very well.  For now, I'm pretty much just using the default configuration and standard features, but as kBase grows that will most likely change.  So you'll probably hear a lot more about cc65 as time goes on.


For building Apple II disk images, there are a number of tools, but the gold standard seems to be CiderPress.  While it's a great tool that I've used for a number of things, it has two problems when used for development.  First, it's Windows only, which is a problem if you're not developing on Windows - and I'm not.  Second, it's gui-driven, not command-line-driven, so it's hard to automate.

For development, especially with cc65, AppleCommander is really superior.  It's functionality is accessible using the command-line, and it even has a special option for cc65 programs.  A general tutorial on AppleCommander is certainly beyond the scope of this post, but I will outline how I'm using it.

One small issue that I ran into resulted from the fact that AppleCommander comes bundled as one jar without any installation utility.  Since I do work on several different machines (2 Macs and 1 Windows), managing the location of this became something of a small headache.  Since the jar file itself is less than 500k in size, which by today's standards is pretty small, my solution was to actually include it in my source branch in the root directory, so I always know where it is no matter which machine I'm on.  When I clone it from Github, it will just be there; it's one less external dependency I have to worry about.

Initially, I had AppleCommander creating blank 140k disk images that I then loaded my binary on to, but for some reason the AppleWin emulator didn't want to read these disk images.  My workaround was to use the emulator to create a blank disk image, and then I just copy the files I need onto it every time I do a build.  I created a sub-directory called "prodos-raw" where I put the blank disk image.  Using AppleCommander I also extracted binary copies of BASIC.SYSTEM and PRODOS, which I also put in the prodos-raw subdirectory.  So when I create my application's disk image, I copy the blank disk image to my build directory, copy PRODOS and BASIC.SYSTEM on to it, and then finally copy my application's binary file.  I can then just boot this disk image in the emulator and load my application.  This is, of course, done in my automated build process, so I don't actually do any of this except testing it in the emulator.

To build my kBase disk:
cp prodos-raw/blank.po ./kbase.po
java -jar AppleCommander- -p kbase.po PRODOS SYS < prodos-raw/PRODOS
java -jar AppleCommander- -p kbase.po BASIC.SYSTEM SYS < prodos-raw/BASIC.SYSTEM

The above assumes that the AC jar is in the current directory, which for my project it will be, as I discussed above.  Also the two files being copied, PRODOS and BASIC.SYSTEM, are specified as type SYS, not BIN.  Another little oddity to AC is that when copying a file onto a disk from the command line, you actually pipe it in from stdin; you don't specify the local file name.  The -p (for put) is what tells AC to put the file on the disk image from stdin.

Then to copy my binary to the disk image:
java -jar AppleCommander- -d kbase.po kbase
java -jar AppleCommander- -cc65 kbase.po kbase BIN < kbase

The first command removes the existing kbase binary on the disk image, if there is one; it does nothing if it's not there.  In my Makefile, I only create the disk image if it doesn't already exist, so the same disk image is reused many times during development unless I do a clean.  Unfortunately, AC's put command won't overwrite an existing file, so you have to do this first if the file may already exist.  The second command is what actually copies the newly built binary onto the disk image.  It's the same as a put command, but instead uses the -cc65 command instead of -p.  I'll be honest, I don't completely understand what impact this has, though the AC help does have some information.  I just don't understand the format of ProDos and cc65 binaries enough to know exactly what it means.

One final thing to note, if you're not familiar with AppleCommander, is that it is a Java application, so you will need to have Java installed.  The web page says the minimum Java is 1.4.2, but if you're using that old of a version, you desperately need to upgrade.  I run it using Java 8 and it runs fine, so no reason not to use the latest and greatest.

To be continued...

No comments:

Post a Comment