11

I have an emulator up and running and access to the asimov ftp site, and I want to learn how to program assembly language on the Apple IIe. What assembler should I use (Merlin? LISA?) and what book or books are the best? Ultimately my goal is to write some games.

  • It would be helpful if you could outline what you already know. Do you already know 6502 assembler and just want the Apple specifics? If not, are you familiar with assembler on other platforms? How much programming experience do you have in general? – Michael Graf Mar 23 at 18:39
  • I know C pretty well, and I know the basics of x86 assembly, but that's pretty much it. – Al Gorithm Mar 23 at 19:22
  • 2
    Then go ahead, find some book about assembly programming on the Apple II and use what is used there. – the busybee Mar 23 at 20:33
  • 1
    Literally any. For a real beginner all will bring enough to start with, thus it's more important to use the same tools as described there than to use 'the best' (whatever that will be). There is no definitive answer, just opinions which creates even more confusion - like I would only suggest ORCA/M - oops, that would add another choice to your list :) – Raffzahn Mar 23 at 21:45
  • 2
    I would suggest the updated classic Assembly Lines, but since you already have an assembly language background, you might also find Apple Graphics & Arcade Game Design a good fit. There's a primer chapter on assembly. You can develop in old assemblers (I used Merlin) or you can x-dev from a modern platform with CA65 or Merlin32 etc. – Nick Westgate Mar 24 at 2:56
9

I realize the OP asked specifically about Assembly Language, but I felt strongly enough about the quality of "Machine Language for Beginners" that I wanted to post it as an answer.

Given that the Apple IIe has a pretty decent built-in monitor, this book is a natural fit for getting the basics down. I completely understand the utility of a good assembler, but sometimes (especially in the 8 bit world) you can get along just fine writing ML.

You can find the PDF version here.

| improve this answer | |
  • As a tween I had that book's initial pressing and it was incredibly accessible. – Joe Mar 24 at 19:22
  • I have a print version of that book somewhere. – Fred Larson Mar 25 at 20:15
7

For getting your first taste of 6502 assembly, I recommend doing the web-based tutorial Easy 6502. You should be able to get through it in a few hours.

Once you've got the basic ideas down, if you're going to learn 6502 assembler at the level of writing non-trivial routines and programs you're going to have to write a fair amount of it.

I recently wrote a post describing my experience getting set up with a traditional self-hosted development system, EDASM on the Apple II. It's certainly worthwhile to learn and interesting to play with, but I don't recommend self-hosting for serious software development as it's compartively slow and painful for no real benefit.

For doing this you should consider cross-development: assembling and doing at least some of your testing on a larger machine (such as a modern Linux or Windows box) and then moving your code over to a full target machine simulator or a target machine itself for the final testing. This general technique is not ahistorical: the first versions of Microsoft BASIC, for example, were written, assembled and tested (in an 8080 simulator) on a PDP-10 before being run on its first target platform, the Altair 8800.

If you're familiar with (and, even better, comfortable with) automated unit testing, I've found this to be an immense aid to learning and programming assembly. It does take some ingenuity, though.

My 8bit development system, which I use for generic 6502 code and Apple I and Apple II development (but which supports other CPUs and platforms) has the following components:

  • Git for revision control.
  • Linux as the host platform, though Windows could work just as well if you're comfortable with that.
  • Vim for editing and command-line scripts for building and testing.
  • The Macro Assembler AS for assembly, though I've also used ASxxxx in the past. My scripts are able to download and build both of these, and install them into a directory in the project.
  • py65 as the 6502 CPU simulator in which I run my unit tests.
  • A unit test framework ("testmc", which I wrote myself) which loads the object files output by the assembler into simulator memory, loads the symbol table used by my tests, and runs pytest unit tests against the code.
  • Various (again, custom-written) scripts for transfer of code to target systems, such as wozmon-deposit to generate "hex records" for input for the Apple 1 monitor and a1send to send the output of that across a serial line to my Apple 1 clone. Similar scripts can be used to generate disk images, start a complete system simulator running your code, and so on.

Here's an example of one of the test sets for a small (8-instruction) convascdigit, a routine to convert an ASCII digit to a binary number:

@pytest.mark.parametrize('char, num', [
    ('0', 0),  ('1', 1),    ('8', 8),  ('9', 9),
    ('A',10),  ('a',10),    ('F',15),  ('f',15),
    ('G',16),  ('g',16),    ('Z',35),  ('z',35),
    ('_', 40), ('\x7F', 40)
])
def test_convascdigit_good(M, char, num):
    M.call(M.symtab.convascdigit, R(a=ord(char), N=1))
    assert R(a=num, N=0) == M.regs

This is actually 14 unit tests, each of which has an input character and expected output value. It loads the A register with that character, sets the N flag, calls convascdigit, and then asserts that after the routine has returned the A register contains the expected output and the N flag is clear (indicating no error). You'll note that it's heavily oriented toward testing edge cases.

Especially when you're starting out, having tests at this level of detail can be very helpful. Issues like off-by-one errors are rampant in assembly as compared to higher-level languages, and often manifest themselves by mysterious crashes, frequently in some different part of the code becuase you made a mistake setting up a value somewhere. (Think about the first time you learned about pointers in C, and then multiply that by ten.)

| improve this answer | |
  • 1
    At a certain point, I agree that doing the actual coding on a modern system will save a lot of grief, but part of this is actually a nostalgia thing, so I want to work inside the Apple IIe for now at least. Thanks for the detailed answer, though! – Al Gorithm Mar 23 at 23:59
  • @AlGorithm That's perfectly fair! For your use case, I would start with the first two examples I gave (Easy 6502, which even ends with implementing a (very) simple game, followed by a bit of EDASM). My post on EDASM gives links to a disk image and the manual I uploaded to archive.org, as well as some hints to get you going on that. From there you might go with a more advanced (1985-level rather than 1979-level) assembler hosted on the Apple II, or move on to cross-development. – cjs Mar 24 at 1:09
  • 1
    For comparison, here's what John Brooks was using for Apple IIgs development under Mac OS X: groups.google.com/d/msg/comp.sys.apple2.programmer/tw902RdWxBE/… . Using Merlin on the Apple II may be beneficial as the code can often be cross-assembled with Merlin 32 without changes; at the very least you won't have to learn a new assembler when moving from retro-assembly to cross-assembly. – fadden Mar 24 at 14:51
  • @fadden Thanks for that link! There's further information here and here, too. I wouldn't worry too much about learning a new assembler, though; that's not difficult and often enlightening. – cjs Mar 24 at 23:25

Not the answer you're looking for? Browse other questions tagged or ask your own question.