[fpc-pascal] SinclairQL (M68K) Port

[Karoly Balogh]

Hi,

On Sat, 20 Mar 2021, Norman Dunbar via fpc-pascal wrote:

> Back in November, we had a visit on our Sinclair QL forum
> (qlforum.co.uk) from ChainQ informing us that he had created a Sinclair
> QL version of Free Pascal for M68K. Quite a number of people showed
> interest, including myself -- and I've not done any Pascal since college
> in the early 1980s.

Yeah, the "bad" influence of #QLvember... :) Sorry, meanwhile I completely
"context switched" away from the QL port, as there was plenty of other
stuff of my plate. It was on my ToDo to get back to it, but actually, I
prefer indeed if the QL community sends patches... I was just not going to
the QL forum lately, there's always one too many retro platforms to care
for. :| Sorry about it!

> Sadly, when testing, I noticed a problem that causes run time errors
> 103, and possibly 102 -- sorry I'm a bit vague I'm not at my QL right
> now. This occurs when any of the following are attempted:
>
> writeln(aFile, 'Some text');
> reset(aFile);

What are you trying to do here? This isn't valid Pascal file handling
code. You have to Assign() a file first, then Reset(), Rewrite() or
Append(), depending on what you want (read or write), then Write/Read/Seek
functions should work on the opened file handle. You need to Close()
afterwards.

> writeln('Some text') works fine to the console, just not to a file as in
> "VAR aFile : Text;" for example.

The RTL on init will open stdin/stdout for you on start, so simple I/O
works on the console, so your writeln() will succeed, regardless of you
trying to reopen the console afterwards.

> There may be other problem areas. I'd like to try and fix these but I'm
> completely unable to find the location of the "writeln" or "reset"
> functions in the source code. I have grepped and Googled to no avail I'm
> afraid.

Write()/Writeln() and WriteStr() are special functions, which the compiler
handles directly, and breaks them down into a series of individual calls,
depending on the type of the parameters in the parameter list printed.
It's required, because Write(), Writeln() and WriteStr() are basically
what you call in C terms a "varargs" function, which is otherwise not part
of Pascal language definition. So you won't find it in the RTL code, and
you probably don't need to touch that code anyway, as everything just
calls do_write() in the end, which is in rtl/sinclairql/sysfile.inc.

If you want to see what happens in the background, for the individual
functions, search for "fpc_write_" in rtl/inc/, you'll see that these are
declared as "compilerproc", which marks the special nature of these calls.
If you know m68k assembly, You can easily identify which functions are
called directly, if you generate assembly code with the -al parameter,
while compiling. Then you can check directly what the compiler does with
your code, and which functions it calls (even if name mangling obscures
them a bit, but it's still possible to understand better what is going on
then). But as I said, you won't need to touch any of these.

The Reset() function's implementation is in rtl/inc/file.inc, along with
Rewrite(). But you most likely don't have to touch these either, because
they internally wrap to do_open(), which is in rtl/sinclairql/sysfile.inc.
This might need to be extended to handle various file open modes (read,
write, overwrite, append, etc) better. Also, integrating console handling
in there might have its own quirks.

> Also, is there any documentation for anyone coming on to the project
> which explains the layout of the code, where to find "stuff"  what needs
> doing and such like? Sort of like a "Beginners' guide to developing Free
> Pascal and/or the RTL"  or similar?

Probably there is something, but it's quite simple in principle, even if
the implementation is a bit more complicated at places. So the RTL
implementation tries to keep the interface and some of the logic platform
independent. This code is in rtl/inc/. And it wraps to system-specific
functions internally, which are already in the sinclairql RTL, just mostly
weren't implemented. Basically any do_<something>() functions which you
see in there.

Additionally, when you get to the implementation of sysutils and classes
unit, the platform independent parts will be in rtl/objpas/, but the same
principle applies.

> It would be helpful to beginners like me, trying to look around and
> fix/implement stuff. I've been all over the Wiki and found this page,
> https://wiki.freepascal.org/FPC_development, but it's not what I was
> looking for although there are some interesting articles on the RTL pages.

Yeah, I think code is the best documentation here, as it's changing quite
fast, although some overview is probably there and it wouldn't hurt to
make it more easy to find that overview it seems. :)

Cheers,
--
Charlie (Chain-Q in the QL forum)