Among programmers, there’s a long-standing tradition whereby one’s first program in any given language is one that simply displays the message “Hello world.”

In this installment of Some Assembly Required, we’re going to create “Hello world.” I’m not going to really explain how it works this time around. We’ll get into understanding the programming next time. The goal, for now, is to simply learn the commands needed to build and run your programs, so we won’t have to deal with that later.

ORCA/M 4.1 (8-bit)

Let’s start by building our program for ORCA/M for 8-bit Apple IIs. Start by launching ORCA.SYSTEM, which will drop you into the ORCA command shell. Type “NEW” to start editing a new file, and press the Return key.

Once you’re in the editor, type in the following listing. Note that the editor is slightly unusual if you’re used to other editors; you’ll want to read through Chapter 3 of the ORCA/M manual to learn its commands.

If your computer is an older Apple II without support for typing lower-case letters, that’s fine, just use all upper-case instead.

COUT     gequ  $FDED                    ;The Apple II character output func.

         keep  HelloWorld

main     start
         ldx   #0                       ;Offset to the first character
loop     lda   msg,x                    ;Get the next character
         cmp   #0                       ;End of the string?
         beq   done                     ;->Yes!
         jsr   COUT                     ;Print it out
         inx                            ;Move on to the next character
         jmp   loop                     ;And continue printing
done     rts                            ;All finished!

msg      dc    c'Hello world.'
         dc    h'0D'
         dc    h'00'
         end

Once you’ve finished entering the code, press control-Q to bring up the quit and save menu, then press “N” to save the file to a new name. Type “HelloWorld.asm” and press return, then press “E” to exit the editor.

Running the program is as simple as typing “RUN HelloWorld.asm”. This will compile, link, and run the program. If any errors occur, type “EDIT HelloWorld.asm” to open the file back up in the editor and find and fix any discrepancies between what you typed and the listing above, then try again.

ORCA/M (16-bit)

To build the program using the 16-bit version of ORCA/M (but still run it as an 8-bit program), start up the ORCA shell by launching ORCA.SYS16 from the Finder. At the command line, first type “ASM65816” to select the assembly code edit mode, then type “EDIT HelloWorld.asm” to start up the editor.

Enter the following code:

         65816 off
         65C02 off                      ;Use 6502 opcodes only

COUT     gequ  $FDED                    ;The Apple II character output func.

         keep  HelloWorld

main     start
         ldx   #0                       ;Offset to the first character
loop     lda   msg,x                    ;Get the next character
         cmp   #0                       ;End of the string?
         beq   done                     ;->Yes!
         jsr   COUT                     ;Print it out
         inx                            ;Move on to the next character
         jmp   loop                     ;And continue printing
done     rts                            ;All finished!

         msb   on
msg      dc    c'Hello world.'
         dc    h'8D'
         dc    h'00'
         end

Once you’ve entered the code, press Command-S to save your work, then Command-Q to quit to the command line prompt. Type “CMPL HelloWorld.asm” to compile and link the program. If any errors occur, type “EDIT HelloWorld.asm” to edit the program and fix the problems, then try again.

Since this program is designed as an 8-bit program, to be run under ProDOS 8, but we’ve built it using the 16-bit version or ORCA, we need to do an extra step. We need to convert it from a GS/OS load file into a ProDOS 8 compatible binary file. To do this, type “MAKEBIN HelloWorld Hello”. This will take the compiled “HelloWorld” program and convert it into an 8-bit binary file named “Hello”.

Then you can quit the ORCA shell, start up Applesoft BASIC, use the PREFIX command to make your way into the directory containing the program, and type “BRUN HELLO” to run it.

Merlin

These instructions are for Merlin 8/16+. Your mileage may vary somewhat on other versions of Merlin.

Once you’ve launched Merlin, press “F” to open the full-screen editor, then enter the following code.

            org       $2000
            xc
            xc

COUT        equ       $FDED         ;Apple II character out func.

            ldx       #0            ;Offset to first character
:loop       lda       msg,x         ;Get the next character
            cmp       #0            ;End of the string?
            beq       :done         ;->Yes!
            jsr       COUT          ;Print it out
            inx                     ;Move on to the next character
            jmp       :loop         ;And continue printing
:done       rts                     ;All finished!

msg         asc       "Hello world."
            dfb       $8D
            dfb       $00

            sav       Hello

Once you’ve entered the code, press Command-6 to save (Type “Hello” for the filename when prompted) and assemble and link your code. You should wind up with a binary file named “Hello” in the same directory as the source code file you just saved (which will be named “Hello.S”).

You can then switch to Applesoft BASIC, use the PREFIX command to make your way into the directory containing the program, and type “BRUN HELLO” to run it, and type “BRUN HELLO” to run the program.

That’s the gist of how to build a simple program in these three environments. Don’t worry about how this stuff works for now. We’ll start learning actual assembly language next time.