This file is
http://www.cs.bham.ac.uk/research/poplog/osx-poplog/porting.txt
Last changed: 8 Jun 2004
Aaron Sloman (http://www.cs.bham.ac.uk/~axs/)

===================================

Luc Beaudoin posted to the poplog-dev list a message about plans for
porting poplog to Mac OSX, in order to allow a project of which he is
the leader to use poplog for part of its software (communicating
with a java application).

In principle the port should not take a long time because we have
sources for a version of poplog that ran on power PC under AIX,
originally developed by ISL, who were then selling poplog.
(www.isl.co.uk -- diverts to SPSS who bought ISL for the Clementine
package, developed on poplog.)

Luc has identified an experienced programmer who can work on this for a
few months, but who does not know pop11 or poplog.

He asked for help on the poplog-dev email list, and I offered the
following provisional work-plan for the programmer (who needs to be
assisted by other helpers who are more familiar with poplog.)

SUGGESTED PROCESS:
I have attempted to draw up a list of possible steps for the programmer
(assuming he already knows a lot about OSX, the PPC machine instruction
set and assembler, and linux/unix).

This list is sketchy and provisional, and the steps would not
necessarily be done exactly in this order. E.g. they could overlap in
time.

CONTENTS

 -- 1. Learn basic pop11
 -- 2. Learning about poplog VM and its role at runtime.
 -- 3. Learning to change the innards of poplog
 -- -- 3.a. He will need to learn the role of the system saved images
 -- -- 3.b. He will need to learn something about system pop11,
 -- -- 3.c. Find out which bits of the run-time system are architecture specific
 -- 4. Get a first idea of where the system saved images come from
 -- 5. Understand how to cross compile poplog
 -- 6. Get a copy of the source files for poplog + PPC and try merging
 -- 7. Try cross-compiling the new OSX tree.
 -- 8. Then rebuild corepop11 using the new system and redo everything
 -- 9. Check out motif and see if it works with pop11 on OSX
 -- 10. Check that the basic X stuff works.
 -- 11. Check out X and XVed.

-- 1. Learn basic pop11

I suspect he will need to spend at least two or three weeks exploring
the language, finding out about its main data-types, the styles of
procedural and functional programming supported, the arithmetic and list
processing mechanism, record and vector classes, macros and syntax
words.

For this the primer may be the best thing available, unless someone has
a better suggestion. It isn't complete for someone with this task.


-- 2. Learning about poplog VM and its role at runtime.

He can then start learning about the poplog VM, e.g. TEACH VM,
then REF VMCODE.

Unfortunately I have no copies of the paper published some time ago by
John Gibson, Robert Smith and myself giving the most complete account
of the poplog VM, in

  booktitle = "Research Directions in Cognitive Science Volume 5: Artificial
    Intelligence",
  editor = "D. Sleeman and N. Bernsen",
  publisher = "Lawrence Erlbaum Associates,",
  pages = "203--231",
  year = "1992",

If your library does not have the book, I should see if I can find it
and photocopy the paper for you. Robert Smith had the troff source
files, and as far as I know they have been lost for years.


-- 3. Learning to change the innards of poplog

Having understood how a working poplog works, he can start learning
how to change its system files in $popsrc and $popexternlib (where the C
code lives) and rebuild the system using pgcomp, pglibr, pglink.

(I don't know if any of the C code will need to be changed.)

He could do all this on solaris, but it would probably be better to use
a PC+linux to get the latest version of poplog (I'll also be better able
to answer questions that arise).


-- -- 3.a. He will need to learn the role of the system saved images

in

    $popsys/*.psv

in doing this.


-- -- 3.b. He will need to learn something about system pop11,
the extended dialect of pop11 used in the system sources. It has several
extensions providing C-like and assembler-like facilities.

Read the files in
    http://www.cs.bham.ac.uk/research/poplog/sysdoc/

packaged in
    http://www.cs.bham.ac.uk/research/poplog/sysdoc.tar.gz

Also HELP POPC, REF POPC

-- -- 3.c. Find out which bits of the run-time system are architecture specific
and used to generate machine code. (Listed below)

Try to understand how they work (in the linux version).


-- 4. Get a first idea of where the system saved images come from

See how the files in

    $popsrc/syscomp

are used to generate popc.psv, poplibr.psv and poplink.psv
and find out how to rebuild those files using

    $popsrc/mksyscomp

Check out which bits of those files are OS- and/or CPU- specific.


-- 5. Understand how to cross compile poplog

It may be useful to start by pretending to cross compile linux poplog.
I.e. go through the steps of producing all the assember files for a
working linux poplog system and use them to build a working system,
which should then perform like the original.

(This need not include editor, X facilities etc.)

The sysdoc files include the poplog porting guide 'ppg'


-- 6. Get a copy of the source files for poplog + PPC and try merging
them into a copy of the linux poplog tree.

The CPU-specific files used in the ppc + aix poplog port
are in this directory:

    http://www.cs.bham.ac.uk/research/poplog/src/master/C.power/

I have made a tar file containing them:

    http://www.cs.bham.ac.uk/research/poplog/src/gz/C.power.tar.gz
        77120 bytes Jun  8 10:07

All the files go into $popsrc/ and $popsrc/syscomp
There are only 17 of them (plus various book-keeping files from Sussex):

src/
    -rw-r--r--    2 axs         16806 Mar 13  1998 C.power/src/aarith.s
    -rw-r--r--    2 axs         14034 Jun  2  1998 C.power/src/aextern.s
    -rw-r--r--    2 axs         15825 May  6  1998 C.power/src/afloat.s
    -rw-r--r--    2 axs          1630 Mar 13  1998 C.power/src/alisp.s
    -rw-r--r--    2 axs          2730 May 14  1998 C.power/src/amain.s
    -rw-r--r--    2 axs         16605 May 19  1998 C.power/src/amisc.s
    -rw-r--r--    2 axs         18672 Apr 29  1998 C.power/src/amove.s
    -rw-r--r--    2 axs         10843 May  8  1998 C.power/src/aprocess.s
    -rw-r--r--    2 axs         10919 Mar 13  1998 C.power/src/aprolog.s
    -rw-r--r--    2 axs          2465 Apr 22  1998 C.power/src/array_cons.p
    -rw-r--r--    2 axs          4145 Apr 23  1998 C.power/src/asignals.s
    -rw-r--r--    2 axs          2807 Mar 20  1998 C.power/src/asm.ph
    -rw-r--r--    2 axs         65727 Jul  6  1998 C.power/src/ass.p
    -rw-r--r--    2 axs          2910 Apr 17  1998 C.power/src/closure_cons.p
    -rw-r--r--    2 axs          4372 Apr 29  1998 C.power/src/drop_code.ph
    -rw-r--r--    2 axs          2200 Apr 17  1998 C.power/src/pdr_compose.p

src/syscomp
    -rw-r--r-- axs/poplog    53272 1998-04-30 16:19:40 C.power/src/syscomp/genproc.p

Each of the above files will have to be compared with the latest
versions of the linux files to see if anything has changed that's
relevant. (e.g. array error handling changed, but I can't recall
where, or what else).

There is also a tar file containing the complete set of sources for
PPC plus AIX. By using a long listing looking for files with only
one or two links I can easily find those that are specific to the
system. The complete collection of system sources for PPC + AIX
(quite a lot of them out of date) is here:

    http://www.cs.bham.ac.uk/research/poplog/src/master/S.powaix
        (over 30 Mbytes. No binaries available.)

I have put that in a tar file (over 7mbytes, most not needed)

    http://www.cs.bham.ac.uk/research/poplog/src/gz/S.poweraix.tar.gz
        7824959 bytes Jun  8 10:08

As far as I can tell (again from using ls -l and looking for files with
no links) there are ONLY these five files specific to that package
and not already included in the above C.power list!!

 src/syscomp/
     -rw-r--r--    1 axs      poplog      13647 Feb 18  1999 asmout.p
     -rw-r--r--    1 axs      poplog       3062 May 19  1998 sysdefs.p

 src/
     -rwxr-xr-x    1 axs      11             85 Feb  5  1998 asm
     -rw-r--r--    1 axs      poplog        956 Feb 26  1998 registers.ph


 extern/lib
     -rw-r--r--    1 axs      11             13 Feb 18  1999 exports

I don't know if they will be relevant to the OSX port: they may be
concerned not with PPC features but with differences between AIX
and other flavours of unix/linux.

Later I'll make a tarball containing those files.

 From a quick scan of link counts in the sussex master tree these seem
to be the ONLY files that will not already be in the linux poplog
tree (notice all the low link counts: most files have 15 to 18 hard
links).

I recommend NOT starting from the S.poweraix tree but instead merging
the few PPC (and AIX??) files into the latest linux source tree which
you already have I think.

This 10 Mb bundle was last changed on April 17

    http://www.cs.bham.ac.uk/research/poplog/new/linux-pc-1553e.tar.gz

It is included in the 21 mbyte bham-linux-poplog.tar.gz which also
last changed then. (It usually changes more frequently because it
contains libraries not included in the core files).

NOTE:
As a precaution, I would request that in every directory with newly
created files you include a copy of the poplog copyright notice
(modified if you wish to acknowledge your contribution, and to limit
your liability):

    http://www.cs.bham.ac.uk/research/poplog/copyright.html
    (This is based on the old XFree86 licence.)

-- 7. Try cross-compiling the new OSX tree.
(First just the core system without ved and X, etc.)

If your helper is brilliant it will run first time and then
he can use the first binary as $popsys/corepop11 (linked
to corepop) and use $popsrc/mksyscomp to create the
system-building files.

He can then test by recompiling all the sources, in
    $usepop/pop/src

-- 8. Then rebuild corepop11 using the new system and redo everything
in 7. to get a fully bootstrapped system.
(save the corepop11 in case!!)

Run $popsrc/mknewpop to get $popsys/newpop.psv

Now use pgcomp and pglibr to compile and archive the editor sources in

    $usepop/pop/ved/src

And try to build a version of basepop11 including Ved, using newpop.

-- 9. Check out motif and see if it works with pop11 on OSX

Find out whether motif is available in OSX and where it is
and make sure that the poplink_command file created in $popsys
by pglink is compatible with it. If not first build a version of
poplog that does not use motif to check out X, as follows.


-- 10. Check that the basic X stuff works.

    Run $popcom/mkXpw

Compiles a lot of C code for X utilities, currenly based on
X11R6

If anything does not work, fix it!!

Test it by running basepop11 and compiling rc_graphic

    basepop11
    uses popxlib
    uses rc_graphic

Then try the examples in the TEACH rc_graphic file
    http://www.cs.bham.ac.uk/research/poplog/doc/popxteach/rc_graphic


-- 11. Check out X and XVed.

This should all work first time using
    $popcom/mkstartup
    $popcom/mkxved

test
    basepop11 +$usepop/pop/lib/psv/startup.psv
    basepop11 +$usepop/pop/lib/psv/xved.psv

Then try it with the Bham extensions
    $poplocal/local/com/mkstartup.local
    $poplocal/local/com/mkxved.local

You can then try out our demos, e.g. the sheepdog demo.

Others may be able to suggest modifications to the above
list of steps.

The only person who has recently done anything remotely like this
is Waldek Hebisch, when he created the HPunix port.

    http://www.cs.bham.ac.uk/research/poplog/hp-poplog

When it is all done I'll have to work with others to agree finally on a
format for the merged poplog tree and incorporate the OSX sources into
it. (I previously suggested a format using a single tree with
sub-directories for architecture specific or OS specific code, where not
handled by compile-time directives in common files. Then a simple
utility could take that tree, plus a specification of OS and CPU and
generate a complete source tree for the combination whenever required.
But that's a topic for another day. This is not as elegant as the sussex
system that depends on links, but avoids the problem of creating all the
links for a new source tree, and others have expressed a wish to avoid
the use of links).

Aaron