Tuesday, October 4, 2016

RC2016/10: Challenge proposal

I know I'm a little late on joining the Retrochallenge, but I've been dealing with the flu the past few days, so I haven't really had the energy or state of mind to write up my proposal.  But here I am, better late than never!

For this challenge, I'm going to try something different than my last few entries.  Instead of a programming challenge, I'm going to try for a bit more of a nostalgia trip.  For the month of October, I'm going on an extended flashback to the early 90's with DOS and Windows 3.1.  My original concept for this challenge was to only use DOS/Windows 3.1 for everything non-work related, but I quickly determined that just wasn't feasible.  The web is just too big a part of our lives now, and the lack of strong encryption and support for modern web standards makes a lot of it inaccessible.

So I'm going to take a middle road.  Although I'll still be using my iMac for my online surfing, I'm going to perform several specific tasks using DOS and/or Windows 3.1 and blog about those.  The tasks will be:

  1. Manage my personal budget.  I currently do this in Google Sheets, but for the month I'll use some DOS or Windows-based program such as Excel or Quattro Pro.
  2. Manage my weekly game with friends.  Once a week, I play a role-playing game named Champions with a group of friends.  I have two Java programs that I wrote that I use to help me run this game, so I'll come up with DOS or Windows replacements.
  3. Computer games.  Even though my first computer was a Commodore 64 and I have fond memories of playing games on it, my greatest affection for old games really comes from the early DOS and Windows years.  Civilization 1 & 2, Colonization, Harpoon, and Doom, among others.
  4. This blog!  While I won't be able to post it online using Windows, I'll author it on my DOS/Windows machine and then post it using my iMac.

So that's my challenge, to jump back 20 years digitally and see how much of my life I can manage using software that's 20+ years old!

Tuesday, August 16, 2016

CP/M on an emulator TRS-80 Model 4P

My TRS-80 Model 4P: You can't really see it but that's CP/M
running off of the FreHD that you also can't really se on top
of the machine.
So as I mentioned in my last blog post, I took an unplanned six-month rectrocomputing siesta.  I had only recently acquired a cool old-but-refurbished TRS-80 Model 4P with a FreHD (an SD-based hard drive emulator) that was already setup to book LS-DOS and CP/M.  Since I'd been wanting to play with CP/M, and I really like the TRS-80 Model 4P, this seemed like a perfect match.  But after some early frustration with trying to transfer CP/M software to the 4P, and with other things coming up IRL, I dropped retrocomputing for a while.

CP/M Emulation

So in my last post, I mentioned that I was kind of itching to do some software project, but due to my current situation, I was really looking for something emulated, not a physical machine.  My TRS-80 Model 4P immediately popped in my head, of course, but my last time I really had problems with emulators.  This was mostly because they wanted me to supply the ROM, but I still didn't have a way to exchange data between my 4P and my Mac.  Well, after some Internet digging (I swear I am the worst googler in the history of humanity), I finally found a working Model 4P ROM.  (Yes, I downloaded the ROM, even though it's copyrighted.  All I can offer is that you trust that I really do own the machine, as evidenced by the photo above.)

So with the 4P ROM in hand, digitally speaking, I tried out the TRS32 emulator first.  Although I'm a Mac person, I do have Windows running both in VMWare and in Boot Camp, so being a Windows-only program isn't necessarily a deal breaker.  And to be honest, it's a good program.  I had a few minor complaints with the interface, but overall it was very functional and easy to setup.  The only real issue I had is that it's shareware, costing $69 to register, and hard drive support was only included in the full version - something I knew I would want, since my 4P had FreHD.  Also, the guy does TRSTools for free, which is a nice little program to read/write TRS-80 floppy disk images.  I'm not opposed to paying for software, and his gift of TRSTools to the community made me even more interested in throwing him some cash, but $70 for an emulator seemed steep to me.

Then I found SDLTRS, an open source cross-platform emulator based on xtrs, an X-Windows emulator.  It is open source, and seems to do everything the full version of TRS32 does, including hard drive support.  The Windows and Linux interfaces are a bit spartan, but the Mac interface is pretty nice, though I wish the Mac supported the same keyboard shortcuts the Windows version does and was a little less mouse-driven.  In any case, it was as easy to get up and running as TRS32 was, and seemed every bit as functional.  So it became an easy choice, and so far I haven't regretted picking SDLTRS over TRS32.

Getting CP/M Running

As you might guess, this was basically just grabbing a disk image, popping it into the virtual floppy drive in SDLTRS, and booting up the VM.  But which CP/M?  There are several for the 4P, the two most common being CP/M Plus and Montezuma Micro's CP/M.  CP/M Plus was limited to CP/M 3.0, and since I already knew I was going with CP/M 2.2, that left only Montezuma's CP/M.  Here's where I got my CP/M image, and in fact most of the CP/M software that I downloaded.

Now before you hop out to that site and start downloading everything like I did, you may want to pause a bit to avoid some mistakes I made.  First, you don't need every CP/M boot disk that's out there.  I just got the last of the Montezuma Micro CP/M boot disks, and that's what I used.  Second, disks will be labeled as either of type COM, DSK, or DMK.  COM means that it's actually going to come as a binary program, not a disk image, so you'll need to copy it to a disk image to run it.  There are two ways to do this, which I'll discuss below.  DSK and DMK are two virtual disk image formats, so either of these are potentially usable in SDLTRS.  However, while SDLTRS does support DMK, I noticed that a lot of them were larger than the 166k floppy drives that the emulated machine supported, so it was hit-or-miss as to whether these worked out of the box.  All the DSK's I downloaded worked without an issue, though, so if something comes in multiple formats, always pick the DSK.  If it does come in DMK only, all is not lost.  It may very well work, so go ahead and try it.  But if it doesn't. the DMK will probably work in TRSTools, so you can copy the files to a temporary directory, then open a blank DSK and copy the files to that.  The DMK may be a larger size than the DSK, so you may have to pick which files you don't need or copy them to multiple DSK images.  I had to do this with the Hard Disk Drivers disk, which was larger than a DSK.  I put the executables on one DSK and the docs on another.  (I'll talk about setting up the hard drive in my next blog post, but at this point, just make sure to grab that disk image.)

Incidentally, I mention using a blank DSK above, but I didn't originally have a blank DSK image.  SDLTRS Floppy Management tools does allow you to create a blank floppy, but I couldn't get these to load once I'd created them, so after a few failed attempts, I gave up with that.  Now TRSTools does say it supports the Montezuma Micro disk format, which it does seem to, but I couldn't see how to create a usable disk image with it.  To get around that, I just made a copy of one of my working DSK image files, opened it in TRSTools, removed all the files, and made sure it was not flagged as write protected.  Then I just renamed it blank.dsk and would just make a copy of this every time I needed a blank floppy.

Now I mentioned above that some software will come as files instead of on DSK or DMK images.  On the download page above I referenced, Zork I could only be downloaded this way, and the first copy of Turbo Pascal 3 I found on another page came as a zip of files.  There are two ways to deal with this.  The first is to use the cpmutils, which is a set of utilities written for xtrs, the base of the SDLTRS emulator, while other way is to use a blank disk image and add them using TRSTools.  

In the SDLTRS distribution is a subdirectory called diskimages, with a disk image called cpmutils.dsk.  Now, annoyingly, this disk image didn't load for me in MM CP/M, but I used TRSTools to copy the files to a usable blank disk image (you can download the result of this here, if you don't want to do this yourself).  This has a bunch of files on it, but the three COM files are EXPORT, IMPORT, and XTRS.  These are special CP/M programs that take advantage of hooks in the emulator to be able to transfer files to and from the local filesystem.  So, for example, to make a disk image for Zork I, all you'd have to do is download the ZORK1.COM file, copy a blank disk image, and then type IMPORT ZORK1.COM ZORK1.COM.  This works in that you don't get any errors, and something is copied, but when I tried to execute ZORK1, it gave me weird, inconsistent results.  (This was after also copying ZORK1.DAT, which you need as well).  When I then used TRSTools to copy the files to a disk image, this worked, so I have to conclude there's some issue with the IMPORT.  If anyone has any clue, please leave a comment.  I should mention, btw, that I did use EXPORT several times successfully, though I wasn't copying any COM files, only text files.

It's too bad that I couldn't get the IMPORT working though.  TRSTools is nice, but as I'm a Mac user, it's a tad of a pain to use.  I use VMWare Fusion to run Windows on my Mac, but I don't usually have that running, and having to switch to the Windows desktop (I don't run the unified desktop because that annoys me too) when I want to use TRSTools bugs me.  But I keep disk images I'm working on in my shared folder between the Mac and Windows VM and that makes it easier.

Building a 4-Drive System

So now that you have a working CP/M system booting off floppy, and a way to transfer files, the last thing I'll mention is about changing your emulated system to a 4-drive system instead of the default 2-drive.  Now as I mentioned in my last blog, I am not very familiar with CP/M, and certainly not familiar with Montezuma CP/M.  So there may be a better way of trying to accomplish what I did.  If so, please let me know in the comments.  But this is what I had to do to get things to work so I could load up disks in four virtual drives.

BTW, if you haven't done so yet, make a copy of the CP/M boot disk image you're going to use.  Also make sure you're working image is not write protected.  This is set in the image file itself, not by the base operating system.  You'll know if it loads in SDLTRS and when you look at the floppy management screen and it has an asterisk beside it.  I didn't see any way to uncheck this in the Windows version, though in the Mac version you can unlock it.  For Windows, you can use TRSTools and just go into Disk Properties under the File menu.

Boot up CP/M and run CONFIG and you'll see the following menu:

Select F for Disk drive definitions and you'll see:

Select 'C' and enter 4 when it asks, "How many drives?"  That should bring you back to the same screen, but showing 4 physical drives instead of 2.  His the ESC key (in SDLTRS, ESC is mapped to the BREAK key and Shift-up arrow is mapped to TRS-80's ESC), and you'll be back at the main menu shown above.

Go ahead and hit 'G' at this point, which will take you to the Disk format definitions menu:

Now you'll notice that you do have four drives defined, A - D, but A and C seem mapped to the same drive, device 0, and B and D to the same device 1.  Now someone who knows more about CP/M may understand this and how to work with this, but for me it just meant I couldn't get and disk images to read correctly in C and D.  So if you're following what I did, select 'C' and you'll see:

The first two options match our new 4-drive disk definitions, but the two DATA format drives don't seem to work, so I set the C and D drives to 'A' to match the two drives that do work.  

Once you've done all that, use ESC to get back to the main menu, and then SAVE THE CONFIG!  It the 'H' option on the main menu.  It's easy to just jump all the way back and forget this; I did it several times.

At that point, hit F10 to reboot and you have a 4-floppy drive system.

In my next post, I'll go through setting up a hard drive for my emulated system.

Tuesday, August 9, 2016

Running silent

As I'm sure no one has noticed, I haven't posted in a while.  I would like to say that I've been so busy with retrocomputing projects that I just haven't had time to post, but the truth would actually be the opposite.  I haven't done anything with retrocomputing for the last four to six months, so I just haven't had anything to post.  There were a number of reasons for me going silent.  My living situation has been in a bit of an upheaval during this time.  I've been sick several times, and my overall energy level has been down (which, for me, is saying quite a bit, since I'm not normally what one would think of energetic in the first place).  And, honestly, I just haven't really been inspired to do anything with retrocomputers.

That started to change about two weeks ago, when I started getting a hankering to do some sort of software project.  I looked around for several things, and started working on a cloud-based web project, until that pissed me off and really sucked away all my interest.  Several other ideas also occurred to me, but finally I decided to come back to the platform I was just getting into when I stopped retrocomputing, the TRS-80 Model 4P.  More specifically, CP/M on the Model 4P.

The Road to CP/M

I used CP/M only briefly back in the day.  When I was a senior in high school, I took a few classes at the local community college, including an introduction to computers which featured CP/M.  I believe they used DEC Rainbows, though I'm fuzzier on that so I could easily be wrong.  But I very clearly remember the cover to the book we used, The CP/M Handbook.  That was it, one semester in one class, and I never used CP/M again.  But being a computer history buff, I read a great deal about CP/M and Gary Kildall and always had a great respect for the man and his contribution to computers.

Before my break, I decided I wanted to explore the world of CP/M, specifically I wanted to do some programming with early Turbo Pascal.  I bought a Kaypro II, but that had a bad second floppy, and Kaypro's CP/M was really built for a two-floppy system.  So I bought a second Kaypro II, which did have two good floppies, though the first one was very slow to load anything.  Also it didn't have the little kickstand that my first Kaypro had, and that bugged me much more than it should have.  So I had the bright idea of putting the good drive from the second machine into the first machine.  I was defeated by two rusted screws, after trying everything I could think of.  The two Kaypro's sit, still disassembled, just a few feet from where I write this, mocking and taunting me.

The Model 4P: A Great CP/M Machine or the Greatest CP/M Machine?

I had read somewhere that the TRS-80 Model 4/4P was an excellent CP/M machine, and I found a nice sale on eBay.  It wasn't the cheapest unit, but the person had cleaned the inside and outside of it, guaranteed that the unit worked, and also included a FreHD unit (a hard drive simulator for the TRS-80 computers using an SD drive, for those who don't know) with the ROM upgraded to take full advantage of it.  As I said, it wasn't the cheapest deal, but just having someone who seemed knowledgeable attest that it is completely functional is worth some extra cash, to those who have experience buying retro computers on eBay.  It even had the latest LSDOS and CP/M as bootable hard disk images on the SD card.  And, sure enough, when I got it it booted up very nicely into both OS's.  The only problem was that while the LSDOS image had a lot of software, the CP/M included the base OS and that was it.  

Well, that's no big deal, thought I.  I can find tons of CP/M software on the net, and I'll just load that up.  Of course, the 4P only has 5.25" drives, and none of my modern machines has a 5.25" drive, so "sneaker net" is out.  Of course, I thought about transferring it through a serial connection, but I couldn't get that to work.  And I couldn't figure out how to transfer anything to the hard drive images on the SD card.  FreHD is a cool device, but the documentation leaves much to be desired.

That's pretty much where I left it, when I began my unplanned, months-long absence from retrocomputing.

In my next post (hopefully within a day or two), I'll follow up with what I'm up to now and what I plan to do.

Thursday, February 4, 2016

My newest acquisition and newest project

Early last month I ordered a 6502 single board computer off of eBay, and it finally got here yesterday.  It was designed and built by Wichit Sirichote, who lives in Thailand, which is why it took so long to get here.  I've been playing with it a little bit and so far it looks like it works exactly as advertised, and I'm hoping to really dive pretty deep into this machine.

If you check out the guy's web page, at the bottom he links to two PDF documents that go along with this system.  The user manual explains how to operate the machine and presents some technical information, while the second document gives 10 sample programs to help learn about the machine.  I spent last night manually typing in the hex form of the programs, which was fun, but by program 9 they were getting big enough that this was getting annoying.  The keyboard is just a bunch of soft buttons with a sheet of some kind of sticker paper on top, so it's really about as good as a membrane keyboard.  So it's good enough for playing around, but it really isn't good for any real programming.

So today I actually figured out how to upload a program.  This wasn't difficult; the user manual explained the process well enough.  But the computer expects the uploaded file to be in Intel or MOS hex file format.  I wasn't familiar with either of these, but a quick Google search turned up what I needed to know.  Both are a text file format to encode binary data in hexadecimal form.  They're very similar formats, differing only slightly.

Here's an example of the Intel hex file format of a simple program from the book that I ran through the assembler:


The format is actually pretty simple once you break it down.  If you're curious I recommend checking out the Intel HEX Wikipedia entry.  The above, however, is just 14 bytes that are loaded into memory at address $0200 (hexadecimal value, or 512 in base-10); the second line is the end-of-file record.  As I said, the MOS hex file format is very similar.  The only difference is that it starts with a ';' instead of a ':', and the record type (the fourth byte, with each two characters comprising one byte) isn't there.  Also the end-of-file line has a slightly different format.

Now the webpage for this kit includes a download with the TASM assembler, which is an older shareware assembler that, as near as I can tell, isn't available for sale anymore.  But the problem is, I think it's a 16-bit DOS app.  When I run it under Windows 7, it says it's incompatible.  I did run it under DOS in VMWare and got a simple little program to compile, but obviously this isn't a long-term solution.  By the way, the irony that a DOS-based assembler is not usable for a guy who's into retro computers (including DOS-based machines) is not lost on me.  All I can say is that I would be happy to do the development in DOS except for two things: I don't have a serial port to upload the program available in my DOS environment (VirtualBox under Mac); and it would just be clunky to have to transfer my program from DOS to an environment where I could upload the program.

With TASM eliminated, I'd really like to use a modern assembler, something that is cross-platform and still supported.  I looked and didn't find any 6502 cross-assemblers that would directly output Intel hex file, so I decided I'll just have to convert my assembled program into Intel hex as a second step in my build, which means I can use any assembler.  So which one?  I've used the assembler with cc65 before, but I wasn't thrilled with it.  cc65 is great for C programming, but less great for assembler, though it's a completely functional assembler.  I looked at several, and decided to try KickAssembler.

Now as a 6502 assembler, KickAssembler seems very C64 oriented, especially since it only generates either a simple binary file or a C64 compatible PRG file.  But for my purposes the PRG should actually do nicely.  It's about as simple a format as one could imagine.  The first two bytes indicates the starting address; the rest is just the raw binary.  I searched for a utility to convert a binary to Intel hex, but didn't find one I liked, so I decided to write one myself.  So the PRG really does work very well, since it contains all the information I need and nothing more.

So what are my plans with this little board?  Here's a rough projection of what I'd like to do (though given my record of being distracted, it's not likely I'll actually finish all this):

  1. Write bin2ihex
  2. Build an emulator using C and Qt (emulators are so much easier for testing/debugging)
  3. Write a new monitor that uses the serial port
That's obviously a good bit of work, especially the new monitor.  I would like to do an interpreted environment like BASIC, but not BASIC as I'm not really a fan of that language.  Maybe Forth or else some other simple language.  

I'll keep posting as I progress.

Saturday, January 30, 2016

Eulogy for a retrochallenge

If you've been following my retrochallenge at all, then you have come to one of two conclusions: Either I'm making progress but not blogging about it, or I'm just no making progress.  Unfortunately it was the latter, not the former.  My last blog earlier this month discussed all the progress I had made: I developed my tool chain and created a Makefile that automated the build process and would be flexible as the project grew.  But this turned out to be pointless since my project never grew.

Why didn't the project go anywhere?  Well, there are a lot of reasons.  I was unexpectedly busy at work, so I didn't have quite as much free time as I normally would.  But more significantly, being so busy at work just left me less motivated to program on my own, since programming is what I do professionally.

Another reason is that, although I had a full LMweek off from work and the family was gone, this turned out to offer me less free time than I had anticipated.  My hobby stuff, including all my retro stuff, was crammed into my "man cave" upstairs in the house, but some rearrangements meant that I could take over the office down below, so I spent part of my free week moving my stuff into my new digs.  This is a big improvement for me, because it allows me to setup two or three retro systems at one time, whereas before I was really limited to only one or maybe two if the second one didn't take up much space.  And I still have my "man cave" which will now become my ham shack (as in ham radio, not pork).

Which leads me into my third reason: Distractions!  Early in the month I purchased a 6502 SBC, so I got distracted by that.  Then @Retrochallenge started tweeting about his ham radio activities, and that inspired me to get back into that hobby.  And even just recently, I purchased a Kaypro 2000.  Although this hasn't arrived yet, I started looking into this system as well.  So basically I lost focus early on and just never really got back to my project.

This is my second retrochallenge, and so far I'm 0 for 2 in terms of completing my project.  But even though I didn't complete last year's either, I felt a lot better about that.  My project involved a lot of reading and learning of the PDP-8 and OS/8, which turned out to take a lot more time than I had expected.  So even though I didn't finish, I learned a lot and felt like I had accomplished a lot.  This time, though, was almost a complete bust.  I did relearn a bit of the xBase platform, and the project skeleton I made for kBase will be usable for future cc65 projects, whether they be for the Apple II or for other 6502 platforms.  I also got a copy of Tom Raidna's TUI library, which I think will be useful for future projects.  So I do feel like I at least gave myself a bit of a step up for future projects, but I definitely didn't really accomplish much.  So I feel pretty unsatisfied with my work this month.

So is this the end for kBase?  Honestly I don't know.  I still like the idea of the project, but I just don't have the motivation to work on it right now.  There are just too many other things I'm playing with at the moment.  And this is a hobby, not work.  But I can't predict what ideas will grab me in the future, and I enjoy working on interpreters, so there's every possibility that I'll come back to this project.  Maybe just in time for Retrochallenge 16/07!

Tuesday, January 12, 2016

RC 2016/01: My development tools, part 2

In my last post, I talked about some of the tools I would use - specifically cc65 and AppleCommander.  But at the time of that post, I hadn't actually done any development yet.  Now I have, though admittedly I still haven't gotten very much done.  I have refined the build process that I used with other cc65 projects so that it's a bit more logical and flexible, and I've incorporated a library from one of my Retrochallenge "competitors"; more on that below.  Nevertheless, I still have a lot of work to go and it's already 12 days into January.  I knew the first half of the month would be slow going, given everything else I have going on, but I've made even less progress than I'd expected.  I'm hoping I can catch up during the second half of this month.

If you're interested in taking a look, check out the repository on Github: https://github.com/hculpan/kbase.  Note that if you build and run it, it's actually a slightly modified version of the A2 CARDIAC program (see my Prepping for the Challenge post for more information on this).  Obviously this will change, but I just wanted some code to test out my build process.

In this post, I'll talk about my build tool, editor, and emulators that I am using.


For my build tool, I went with the Make utility.  There are almost certainly better tools out there for C development, but honestly I'm reasonably familiar with Make so it's just easy for me to use.  I also like that it makes no assumptions and I'm in complete control of what build targets are available, what commands get executed, etc.  In my professional life as a Java developer, I use Maven, which really does most of the work for you.  I'm happy with that build tool, but it can be a pain when you want it to do something that it doesn't want to do.  But with Make there are no such issues; it does only what I tell it to do and nothing more.  For a larger project, like those I work on in my job, this could be bad and hard to manager, but for a small project like kBase, this is much easier.

Of course, with Linux you almost certainly already have Make installed, and on Mac OS X, it gets installed when you install Apple's command line development tools (see cc65 above).  With Windows, though, it's a bit more of an issue.  My solution is Cygwin, which is one of the first things I install on any Windows machine anyway.  If you don't want to install Cygwin, there is MinGW.  Otherwise, I'm not really sure how to get Make on Windows, but that's just because I don't generally do C/C++ on Windows, and when I do I happily use the Cygwin tools.  There are also other newer cross-platform build tools, but since I'm happy with Make, I haven't really investigated alternatives.

Atom editor

For code editing, I use the relatively new Atom editor.  Overall I like the editor, but honestly it's two best features for me are that it's cross-platform and that it can be launched from the command line.  This last is a rare feature among editors, and for a command line guy like me, a welcome one.  I can type "atom ." at the command line (and I always have a command prompt open), and it will open with all the files in the current directory listed in the left panel, ready for me to select.  It's almost like having a project manager built into the tool without having all the constraints of a full-blown IDE.  Otherwise, I just use it as a text editor.  I haven't installed any plugins to launch builds from my editor or anything else.  It does have C and Makefile syntax highlighting built in, which is nice.

One way I think I'm different than many other developers is that I'm actually pretty neutral about my editor.  I can use anything from Vi to a full IDE without too much complaint, as long as it's not Emacs.  During my last Retrochallenge, I even began to like TECO, the PDP-8 editor, so really I'm pretty flexible when it comes to my editor.  As a side note, it is a little ironic that I hate Emacs but like TECO, since Emacs actually started as a set of macros for TECO.


As I've said, I'm doing development on both Mac and Windows, and this is the one category of tools that I really couldn't find a good cross-platform solution.  However, there are good emulators for both platforms, and I chose probably the two most obvious choices, AppleWin for Windows and Virtual II for Mac.  They are both good emulators and both do what I need, at least so far.  But honestly most any emulator would probably do what I need.  The only issues I would be likely to run into would be printer support and extended memory, since I'm pretty certain I won't be implementing dBase III+ in 64k.
Having said all that, I will say that Virtual II may be the best emulator I've used for any platform so far, and it is the only one that I paid for (the others all being open source, not that I've been using them illegally).  Honestly, I haven't used much of its advanced features, but it comes the closest of any emulator to really feeling like a real retro computer.  Overall I love the interface, and I love the sounds it uses to simulate a real disk drive.  So if you're looking for an Apple IIe emulator for Mac OS X, I would recommend you give it a try.

The Real Hardware

The final tools I wanted to mention are the actual hardware that kBase will be running on.  That will be primarily an Apple IIgs with 4 MB of ram, both 5.25" and 3.5" floppy drives, and a Classic IDE for Apple II emulator my hard drives (though I have a CFFA3000 on order).  Obviously I usually run GS/OS, but for this project I'll be using it as a standard Apple II.  I also have an Apple IIc with 512k ram, which is usually packed up but will also be used as another test platform for this project.

TUI Library

Finally, I wanted to mention that Tom Raidna (@TRaidnaComputes on Twitter, blog at https://traidna.wordpress.com/) nicely offered to share his project with me, since we're both working with cc65 and I will need a text interface for kBase.  His project, Retro C IDE, is going to allow you to layout a text-based interface and then generate the C code for that interface from his Windows-based application.  Now since it is Windows-based, that's less useful for me, but as it turns out he's generating code for his TUI Library that he had earlier developed - and this library is definitely of use to me.  So he has shared this library with me, which I hope will simplify my efforts to develop the interface for kBase.  So kudos to Tom!

Next Steps

Hopefully in my next blog post, I'll be able to report some actual progress with kBase.  First, I'll build the basic user interface (the "." prompt) and a simple parser to interpret commands.  After that, I'll hopefully be at a point where I can read a dBase database file.

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...