Assembler for Learning Assembly Language Programming ORCA vs Merlin vs ???

[tou...@gmail.com]

Many years since doing any programming on the Apple IIs, I've been thinking about learning to do some assembly language programming on them.

In the past, after initially learning to program in Applesoft (mainly by typing in and studying programs from Nibble), I mainly used Applesoft, ZBasic,and TML Pascal for the little bit of programming I did. At one point I purchased ORCA/M, ORCA/Pascal, and ORCA/C, but ended up mostly using TML Pascal because I liked the GUI better than ORCA/Pascal's. I played around with EDASM/TED and Big Mac at one point, but didn't really do anything useful. Anyhow, all of that was 25+ years ago, so I'm starting fresh.

I don't read a lot here about the ORCA/M Assembler and was wondering if it would be a good choice to use for 8-bit and eventually 16-bit toolbox programming. It would be nice to start out with something that will scale up to the IIGS programming, instead of starting out with on older 8-bit only DOS 3.3 program.

Merlin seems pretty popular, so I was wondering if it would be a better choice to learn with. Maybe some other choice like Lisa or SC? There seem to be many available.

Thanks for any insights,
-Dave

[D Finnigan]

tou...@gmail.com wrote:
> Many years since doing any programming on the Apple IIs, I've been
> thinking
> about learning to do some assembly language programming on them.

I learned assembly language on the Apple II first by using the
Mini-Assembler built in to the Old Monitor ROM, the enhanced Apple IIe, or
the Apple IIgs.

I also hand-wrote and hand-assembled the code into machine language and
manually entered it using the Monitor. The purpose here was to better learn
and memorize the hex opcodes. This is useful because you'll often be
patching code in RAM to debug it, so there's a handful of opcodes to be
memorized.

The programs I wrote were only a couple dozen bytes in length at most.

After I'd mastered the basics of the instruction set & the simpler
addressing modes, then I moved on the Big Mac and Merlin.

I found the biggest learning curve was the addressing modes, understanding
how they work, and knowing which mode is best suited for which situation.

--
]DF$
The New Apple II User's Guide:
https://macgui.com/newa2guide/

[Andy McFadden]

On Tuesday, July 30, 2019 at 8:37:06 AM UTC-7, tou...@gmail.com wrote:
> Merlin seems pretty popular, so I was wondering if it would be a better choice to learn with. Maybe some other choice like Lisa or SC? There seem to be many available.

The most popular are Merlin, which is also available as a cross-assembler (Merlin 32), and Orca/M, which was part of the APW tools that Apple distributed for the IIgs.

Are you committed to doing the work on the target machine (to get that full retro experience)? It's pretty common to cross-assemble and copy the binaries across, especially for larger projects. (Which is nothing new... I remember Andy Nicholas doing GS/ShrinkIt builds on a Mac.)

I wrote fdraw using Merlin on an Apple IIgs, going almost full retro. I say "almost" because the IIgs was actually a copy of KEGS running under Windows.

[Frank M.]

you're gonna want to check out http://www.brutaldeluxe.fr/ for lots of gs programming stuff, source code, etc (home of Merlin32 and CADIUS).

https://www.brutaldeluxe.fr/products/crossdevtools/merlin/

[tou...@gmail.com]

David, I remember playing around some with the mini-assembler, too. I started out with an Apple II with the integer basic ROM. I didn't get very far with any of them, though.

Andy, I'm thinking more of the "almost retro" mode, using an emulator (under Windows or Linux). But I also have some real Apples that worked when they were last set up a few years ago. I plan to at least get a IIGS up and running again at some point.

I'm leaning toward the ORCA/M, since I already own it and some of the other Byteworks tools, and have used parts of the Byteworks suite in the past. But Merlin looks to be pretty popular around here, and the program and docs seem to be readily available on the net so I'm not against trying it, since I'm essentially starting over.

-Dave

[D Finnigan]

Andy McFadden wrote:
> On Tuesday, July 30, 2019 at 8:37:06 AM UTC-7, tou...@gmail.com wrote:
>> Merlin seems pretty popular, so I was wondering if it would be a better
>> choice to learn with. Maybe some other choice like Lisa or SC? There seem
>> to be many available.
>
> The most popular are Merlin, which is also available as a cross-assembler
> (Merlin 32), and Orca/M, which was part of the APW tools that Apple
> distributed for the IIgs.
>
> Are you committed to doing the work on the target machine (to get that
> full
> retro experience)?

If you use a native Apple II assembler on real Apple II hardware, as I
always do, I highly recommend an accelerator. I use a Transwarp in my Apple
IIe. But if you have an Apple IIgs, you already get a little speed boost.
;-)

[D Finnigan]

tou...@gmail.com wrote:
>
> I'm leaning toward the ORCA/M, since I already own it and some of the
> other
> Byteworks tools, and have used parts of the Byteworks suite in the past.
>

My impression of ORCA/M is that it really shines when working on a
large-scale project. Also, ORCA/M will integrate with the other Byteworks
languages. For small to medium-size code bases, Merlin is just fine.

[tou...@gmail.com]

On Tuesday, July 30, 2019 at 8:09:44 PM UTC-4, D Finnigan wrote:
>
> If you use a native Apple II assembler on real Apple II hardware, as I
> always do, I highly recommend an accelerator. I use a Transwarp in my Apple
> IIe. But if you have an Apple IIgs, you already get a little speed boost.
> ;-)
>
> --
> ]DF$
> The New Apple II User's Guide:
> https://macgui.com/newa2guide/

I've got a TranswarpGS in my IIGS. Stock 8 MHz but it really helps.
-Dave

[tou...@gmail.com]

On Tuesday, July 30, 2019 at 5:27:28 PM UTC-4, Frank M. wrote:
> you're gonna want to check out http://www.brutaldeluxe.fr/ for lots of gs programming stuff, source code, etc (home of Merlin32 and CADIUS).
>
> https://www.brutaldeluxe.fr/products/crossdevtools/merlin/

Thanks Frank. I saw the BrutalDeluxe stuff. Lots of great information on that site. As for Merlin32, I think I'm going to start out in "semi-retro" mode, though. If I actually get into any heavy programming, which I doubt, I might look into it again.
-Dave

[tou...@gmail.com]

On Tuesday, July 30, 2019 at 8:11:27 PM UTC-4, D Finnigan wrote:
>
> My impression of ORCA/M is that it really shines when working on a
> large-scale project. Also, ORCA/M will integrate with the other Byteworks
> languages. For small to medium-size code bases, Merlin is just fine.
>
> --
> ]DF$
> The New Apple II User's Guide:
> https://macgui.com/newa2guide/

I don't see any large-scale projects in my future, but like the idea of having other languages and tools under the same system. I think I'm going to install both ORCA and Merlin in an emulator and play around with them to see which I like better.

So, there seems to be a bunch of different versions of Merlin. I'm guessing Merlin16+ is the latest to use on a GS?

-Dave

[tou...@gmail.com]

Update:

I installed ORCA/M 2.1.0 and Merlin 16+ 4.08 (BTW, are those the latest versions?) onto a clean GSOS 6.0.1 hard drive image for use with ActiveGS & GSPort, and played around with them, going through the "Hello World" examples in each, and making a few changes to them to see what happens.

I have to say, I think I like Merlin better, especially for learning assembly language. ORCA/M seemed more like a "high-level" language, at least with the example program in the manual. Everything was done through calls to macros or libraries. That's probably great for production, but not so good for understanding what's going on.

Merlin's example actually used opcodes to do things, which is more what I'm looking for. I want something a little above the mini-assembler to learn with, but that is powerful enough to be useful as my learning progresses. It looks like Merlin is that assembler. I think I see why it's so popular.

I'm sure both of them can do things either way, and it's just how the authors chose the examples to present, so nothing is set in stone after just one evening of playing around. But Merlin is definitely easy to use and looks good at this point. There also seems to be more Merlin source code to examine and play around with than other assemblers, which is one of the ways I learn.

Thanks for the help,
-Dave

[Antoine Vignau]

* Dave,

mx %11
org $800

ldx #0
]lp lda mySTR,x
beq theEND
jsr COUT
inx
bne ]lp
theEND rts

mySTR asc "There is a 4.12 of Merlin 16+."00

* av

[Andy McFadden]

On Wednesday, July 31, 2019 at 7:51:49 PM UTC-7, tou...@gmail.com wrote:
> There also seems to be more Merlin source code to examine and play around with than other assemblers, which is one of the ways I learn.

If you'd like a IIgs example project in Orca/M, including a "permanent" init file, classic desk accessory, finder extension, desktop application, and other random junk, you can download "hpsource.shk" from https://fadden.com/apple2/hardpressed.html .

Probably not the best place to start, but if you're wondering what a large project looks like in Orca/M... it's a large project in Orca/M.

I also used a make utility, the ROSE editor, one of the Rez generators (Genesys), an icon editor (DIcEd), GSBug + NiftyList, a debugging card, ...

Start with Merlin and 8-bit software. :-)

[tou...@gmail.com]

* Antoine,

mx %11 ;8-bit mode
org $800 ;program start address

COUT equ #FDED ;had to define this - a "learning experience"? :)

ldx #0 ; load x-register with zero
]lp lda mySTR,x ;label start of loop - load character number 'x' from myStr
beq theEND ;exit loop if $00 encountered (end of string)
jsr COUT ;output character to screen
inx ;icrement counter (x-reg)
bne ]lp ;goto ]lp if not zero
theEND rts ; quit back to system

mySTR asc "I can't get it to work - See below :("00

* Dave

It assembles fine after defining COUT, but I get no output and (no errors) when run.

I suspect it has something to do with SystemEnvironmetInit, SysIOStartup, and SysIOShutDown?

The Orca/M "Hello World" example acted the same way and wouldn't work without:

jsl SystemEnvironmentInit
jsl SyusIOStartup

before trying to print anything to the screen, and ending with

jsl SysIOShutDown

but I cant for the life of me figure out how to do this in Merlin. And I can't find the addresses to define for these three routines.

Is there a library or macro or something that I need to use in Merlin?

I'm running Merlin 16+ 4.08 under GS/OS System 6.0.1 in ActiveGS emulator.

-Dave

[tou...@gmail.com]

Thanks Andy, I'll grab that and take a look. I don't expect to get into that large of a project, but it should be interesting to study at some point.

I'm thinking Merlin and 8-bit software is a great place to start. If I can get it working. See my post above.

Thanks,
-Dave

[James Davis]

On Thursday, August 1, 2019 at 4:07:36 PM UTC-7, tou...@gmail.com wrote:

> but I cant for the life of me figure out how to do this in Merlin.
>

> -Dave

IIRC, the Merlin User Manuals are available for download on Asimov.

[tou...@gmail.com]

Thanks, James.

I have the Merlin 8/16 manual and Merlin 16+ Supplement (probably got them from there), but I can't find the solution in them.

After studying this some more, it seems to me that the Orca/M example must be generating a file for GSOS instead of 8-bit code. So that's no help. I thought from reading the Merlin manual that the mx %11 statement set the assembler for 8-bit mode, and the programs run ok under ProDOS 8, but they don't show the output. I also tried the XC OFF directive, like suggested in the Merlin 16+ Supplement, but it didn't change the result either.

I also tried it with Merlin 16 (not 16+) and got the same result. I tried it again with Merlin 16, booting the ProDOS 8 disk it was on instead of launching from GSOS, and it still didn't work.

I tried it with Merlin 8 and it worked (after removing the mx %11 statement, which wouldn't apply)

So, I still haven't figured out how to make Merlin 16 or 16+ make a program that works under ProDOS 8.

I haven't given up, though. Just need to get some real work done before messing with it anymore.

Thanks,
-Dave

[Antoine Vignau]

Hi Dave,
If you are using Orcam, I cannot help you, but with Merlin and with the forgotten COUT = $FDED ; with a dollar sign, then it should work ;-)

Antoine

[andrew....@writeme.com]

On Friday, August 2, 2019 at 1:55:29 PM UTC+10, tou...@gmail.com wrote:
> After studying this some more, it seems to me that the Orca/M example must be generating a file for GSOS instead of 8-bit code.

It is.

> I also tried it with Merlin 16 (not 16+) and got the same result. I tried it again with Merlin 16, booting the ProDOS 8 disk it was on instead of launching from GSOS, and it still didn't work.

You don't state how you got from source code to object code on disk in a form that would boot.

Adding this to the end will create a binary file of the output in your current directory:
SAV EXAMPLE

You could then expect to move that file to a bootable ProDOS disk which starts BASIC.SYSTEM and end up at the ] prompt after booting it and from where you could

]BRUN EXAMPLE

I happen to have multiple hard drive images connected via smartport and after starting BASIC.SYSTEM from GS.OS I was not able to PREFIX to my volume. This is probably a problem with the smartport mapping in the ProDOS I am using.

When I copied my binary file to a volume that I could prefix to, BRUN EXAMPLE showed the output on my screen.

Regards,
Andrew

[tou...@gmail.com]

Antoine,
I'm using Merlin 16+ v4.08. I tried under ORCA/M because I couldn't get Merlin to work.

I did have the $ in the COUT equ $FDED staement. I just missed it when I typed in the message. The program assembles and runs fine with Merlin 16/16+, it just doesn't show any text on the screen. It works using Merlin 8, though.

Thanks,
Dave

[tou...@gmail.com]

Andrew,

I meant that I booted Merlin 16 (not 16+) from a disk instead of running from the Finder. Just another thing I tried, but it didn't make any difference.

Here's my workflow (in ActiveX emulator, also tried it in GSPort):
Start Merlin 16+ from System 6.0.1 hard drive image
D(os commands)
Prefix myprogs
F(ull screen editor)
enter program
oa-A(ssemble)
oa-Q(quit editor)
S(ave source file) as AV1
O (save object file) as AV1
D(os commands)
-AV1

and AV1 runs and I get an Applesoft prompt again, but no text.

I also tried to run AV1 by exiting Merlin and starting Basic.System from the Finder, which didn't work either. So I booted a ProDOS disk and tried to run from there with same problem.

I also tried copying the AV1.BIN file to a Prodos Boot disk, booting, and BRUN AV1, but got the same result. I also used the SAV AV1 directive you mentioned, but no difference in output.

If I use Merlin 8, everything works as expected, but I can't get Merlin 16 to output the string to the screen.

Arrrrgh! I know it's something simple that I just don't know about, but it's frustrating not being able to get a simple "hello world" program running.

Thanks,
-Dave

[tou...@gmail.com]

If anyone's interested in looking at it, here's a link to a bootable ProDOS disk image with the Merlin source and binary files.

https://drive.google.com/file/d/1wKdu9P6lW-lKNPQMPNWqzbsvlQxorcMV/view?usp=sharing

When I run the file AV1, all I get is an Applesoft cursor back with no errors.

Thanks,
Dave

[tou...@gmail.com]

And here's a link to a screencap of the program in AppleWin's debugger.

https://drive.google.com/file/d/1U9fOL61QA5SwY-WwoUITav2dOUKCmgVe/view?usp=sharing.

I don't know much, but it looks to me like the characters are being sent to COUT, so why aren't they showing up on the screen?

-Dave

[eeastman]

Thanks for sharing your experience. Not may reviews these days from a beginner like me, I appreciate your perspective a little easier. I hope you post more on your experience and your process as you go forward.
-Ed

[andrew....@writeme.com]

On Friday, August 2, 2019 at 11:54:05 PM UTC+10, tou...@gmail.com wrote:
> If anyone's interested in looking at it, here's a link to a bootable ProDOS disk image with the Merlin source and binary files.

Hmmm. I can open that 140k image in Ciderpress, but the image is not recognised by GS/OS when I try to mount it in Finder under GSport... I'm not sure what is going on there. It has been a while since I've used 140k images in 5.25 drives so perhaps I haven't configured something properly.

I had a look at the binary file within Ciderpress. It looks correct to me. I don't know what your issue is.

Regards,
Andrew

[denisb...@gmail.com]

The object code in AV1 bears no resemblance to the source code in AV1.S. Did you assemble the source? Where did it go?

[denisb...@gmail.com]

Sorry, ignore that message. I confused myself.

Now, surely it is loading the first character, comparing it to zero and then exiting. Shouldn't the BNE be BEQ?

[Antoine Vignau]

First is beq, second is bne. from memory, X is preserved so we are supposed to be good,
av

[tou...@gmail.com]

Thanks for looking at this, everybody.

To be honest, I’m not sure the code in the file I uploaded is the same as what’s shown in the debugger. I have typed it in several times to try in different different assemblers and may have gotten the bne and beq switched at some point.

I can’t check right now because I’m away from the computer, spending time with my granddaughters, but I’ll check it this evening and post in update with my findings.

-Dave

[tou...@gmail.com]

Not sure why you're having trouble with the disk image. I downloaded it using the Google Drive link I posted and it loaded in GSport and ActiveGS OK. Anyhow, it's a moot point. The issues has been (mostly) solved... See below.

[tou...@gmail.com]

On Saturday, August 3, 2019 at 3:58:50 AM UTC-4, denisb...@gmail.com wrote:
>
> Now, surely it is loading the first character, comparing it to zero and then exiting. Shouldn't the BNE be BEQ?

On Saturday, August 3, 2019 at 8:14:15 AM UTC-4, Antoine Vignau wrote:
> First is beq, second is bne. from memory, X is preserved so we are supposed to be good,
> av

That is indeed the answer! When I first typed in the code, it appears that I typed BNE instead of BEQ after loading a character, before sending it to COUT.

When I typed it into Merlin 8, I got it right, and that's why it worked then.

When I typed it again for Merlin 16 (not 16+) I made the same error, or maybe I just copied the original Merlin 16+ source file, so the error was there.

I changed the first BNE to BEQ in Merlin 16+ and it worked, but only after quitting Merlin 16+, running BASIC.SYSTEM, and running the binary from there using -AV1. It DID NOT work when running from the Merlin 16+ Main Menu Disk Command line, using -AV1.

Further investigation shows that it will run from the Merlin 16 (not+) or Merlin 8 Main Menu Disk Command line.

So, after more study of the Merlin 16+ Supplement manual, I found a discussion about EXE files on page 28 saying:

"When an EXE file is launched from the Main Menu disk command, or by the Command Box as a shell command, it is executed in full 16=bit mode (as per Apple Protocol)...

As I read further, it started getting into things I don't quite understand yet.

So, is there a way to launch the assembled 8-bit file as an 8-bit program without leaving Merlin and starting Basic System, like it appears that Merlin 16(not+) does? That seems like a major time waster when developing an 8-bit program.

Thanks again!
-Dave

[Andrew Roughan]

tou...@gmail.com <tou...@gmail.com> wrote:
> So, after more study of the Merlin 16+ Supplement manual, I found a
> discussion about EXE files

EXE files allow user built commands to be executed from the M16+ command
prompt or from a command file.

This is not really the mechanism you want.

> So, is there a way to launch the assembled 8-bit file as an 8-bit program
> without leaving Merlin and starting Basic System, like it appears that
> Merlin 16(not+) does?

I don’t think so. M16+ is geared towards GS development and it’s command
line doesn’t make P8 or Bank 0 memory available.

Use the correct tool for what you want to do. Merlin 8/16 for Prodos 8
targeted code or 16+ for GS/OS.

Regards
Andrew

[tou...@gmail.com]

Thanks, Andrew.

That sounds reasonable. I just wondered if I was missing something.

-Dave