2012-04-24 01:22:36 +00:00
Retro68
=======
2015-09-12 22:33:40 +00:00
A GCC-based cross-compilation environment for 68K and PowerPC Macs.
2019-01-01 23:19:42 +00:00
Why? Because there is no decent C++17 Compiler targeting Apple's System 6.
2012-04-24 01:22:36 +00:00
If that's not a sufficient reason for you, I'm sure you will find
2015-10-07 00:11:44 +00:00
something more useful elsewhere.
2012-04-24 01:22:36 +00:00
2014-09-12 23:03:45 +00:00
If you are crazy enough to try it out, please say hello at
wolfgang.thaller@gmx.net.
2015-09-12 22:33:40 +00:00
Installing/Building
-------------------
2019-11-13 22:23:28 +00:00
The Retro68 git repository uses submodules; be sure to use the `--recursive` option to `git clone` or use
git submodule update --init
after cloning. To get the latest changes, use
git pull
git submodule update
2021-12-08 21:25:19 +00:00
Note: There is now experimental support for the [Nix Package Manager ](www.nixos.org ). If you're a nix user, skip ahead to the [Using Retro68 with Nix ](#using-retro68-with-nix ) section.
2015-09-12 22:33:40 +00:00
### Prerequisites
2012-04-24 01:22:36 +00:00
2018-01-03 06:17:53 +00:00
- Linux, Mac OS X or Windows (via Cygwin)
2015-01-19 23:05:54 +00:00
- boost
2019-01-23 09:56:52 +00:00
- CMake 3.9 or later
2014-09-12 23:03:45 +00:00
- GCC dependencies: GMP 4.2+, MPFR 2.3.1+ and MPC 0.8.0+
2015-01-19 23:05:54 +00:00
- bison version 3.0.2 or later
2019-09-27 21:06:06 +00:00
- ruby version 2.1 or later
2019-11-13 22:23:28 +00:00
- flex
- texinfo
2019-09-27 21:06:06 +00:00
- Recommended: Apple Universal Interfaces (version 3.x; version 3.4 is tested)
2012-04-24 01:22:36 +00:00
- An ancient Mac and/or an emulator.
2014-09-12 23:54:02 +00:00
For Ubuntu Linux, the following should help a bit:
2019-11-13 22:23:28 +00:00
sudo apt-get install cmake libgmp-dev libmpfr-dev libmpc-dev libboost-all-dev bison flex texinfo ruby
2014-09-12 23:54:02 +00:00
2022-07-13 07:17:40 +00:00
For Arch Linux, this should do the trick:
sudo pacman -S --needed cmake gmp mpfr libmpc boost bison flex texinfo ruby
2014-09-17 00:10:04 +00:00
On a Mac, get the homebrew package manager and:
2023-10-23 20:08:19 +00:00
brew install boost cmake gmp mpfr libmpc bison texinfo
2014-09-17 00:10:04 +00:00
2017-10-08 00:36:59 +00:00
You can also run Retro68 on a PowerMac G4 or G5 running Mac OS 10.4 (Tiger).
2014-10-17 20:51:42 +00:00
In that case, get the tigerbrew package manager and
2023-10-23 20:08:19 +00:00
brew install gcc cmake gmp mpfr libmpc bison texinfo
2017-10-08 00:36:59 +00:00
brew install boost --c++11
2014-10-17 20:51:42 +00:00
2019-09-27 21:06:06 +00:00
### Apple Universal Interfaces vs. Multiversal Interfaces
2014-09-12 23:54:02 +00:00
2019-09-27 21:06:06 +00:00
To compile code for the Mac, you need header files and libraries describing
the APIs. There are two choices: Apple's Universal Interfaces, or the
brand-new open source reimplementation, the Multiversal Interfaces.
The Multiversal Interfaces are included with Retro68 out of the box, and they
are free software. However, they are incomplete and may still contain serious
bugs. Missing things include Carbon, MacTCP, OpenTransport, Navigation Services,
and basically everything introduced after System 7.0.
2017-04-23 15:02:11 +00:00
2014-09-12 23:54:02 +00:00
The Universal Interfaces used to be a free download from Apple. However,
2017-04-23 15:02:11 +00:00
they have taken the site off-line and the license agreement does not allow
redistribution, which is why it's not included in this repository.
The concept of fair use might cover keeping it available for reasons of historical
interest, or it might not. I am not a lawyer.
2019-09-27 21:06:06 +00:00
If you find a copy of Apple's Universal Interfaces, you can put it
inside the InterfacesAndLibraries directory in the source tree, and
Version 3.4 has received the most testing, but any 3.x version could theoretically
work. The exact directory layout inside the InterfacesAndLibraries directory does
not matter. It will be picked up automatically when Retro68 is built.
2017-04-23 15:02:11 +00:00
The Universal Interfaces were also included with Apple's free-to-download
Macintosh Programmer's Workshop (MPW; redistribution is not officially allowed, either)
and with Metrowerks CodeWarrior.
One of the most easily found downloads is the MPW 3.5 Golden Master release,
2019-09-27 21:06:06 +00:00
usually in a file named *MPW-GM.img.bin* or *mpw-gm.img_.bin* . At the time of
this writing, this can be found at:
2014-09-12 23:54:02 +00:00
2017-04-23 15:02:11 +00:00
http://macintoshgarden.org/apps/macintosh-programmers-workshop
https://www.macintoshrepository.org/1360-macintosh-programmer-s-workshop-mpw-3-0-to-3-5
2019-09-27 21:06:06 +00:00
https://staticky.com/mirrors/ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./MPW-GM_Images/MPW-GM.img.bin
2017-04-23 15:02:11 +00:00
You will need a Mac or a Mac emulator (with DiscCopy) to read that file.
2012-04-24 01:22:36 +00:00
2017-10-17 21:28:14 +00:00
### Windows Compilation using Cygwin
You can compile Retro68 on Windows using via a Cygwin terminal. When installing
Cygwin, select the following packages in the Cygwin Setup program (as per the dependencies
listed above):
- bison
- cmake
2018-01-03 06:17:53 +00:00
- flex
2017-10-17 21:28:14 +00:00
- gcc-core
- gcc-g++
- libboost-devel
- libgmp-devel
- libmpc-devel
- libmpfr-devel
- make
2018-01-03 06:17:53 +00:00
- texinfo
2017-10-17 21:28:14 +00:00
- zlib-devel
Additional dependencies will be automatically installed.
Note that compilation via Cygwin is around 3X slower than other platforms.
2014-09-12 23:54:02 +00:00
2015-09-12 22:33:40 +00:00
### Compiling Retro68
2012-04-24 01:22:36 +00:00
2014-09-12 23:54:02 +00:00
Once you have all the prerequisites, execute these commands from the top level
of the Retro68 directory:
2012-04-24 01:22:36 +00:00
2021-10-25 11:35:43 +00:00
mkdir ../Retro68-build
2021-12-23 23:36:25 +00:00
cd ../Retro68-build
2017-04-23 16:01:28 +00:00
../Retro68/build-toolchain.bash
2012-04-24 01:22:36 +00:00
The toolchain will be installed in the "toolchain" directory inside
2017-10-06 23:37:53 +00:00
the build directory. All the commands are in `toolchain/bin` , so you might want
to add that to your `PATH` .
2012-04-24 01:22:36 +00:00
2017-04-23 16:27:06 +00:00
If you're building this on a PowerMac running Mac OS X 10.4, tell the build script
2017-10-08 08:40:47 +00:00
to use the gcc you've installed via tigerbrew:
2017-04-23 16:27:06 +00:00
2019-01-22 17:28:44 +00:00
../Retro68/build-toolchain.bash --host-cxx-compiler=g++-7 --host-c-compiler=gcc-7
2017-04-23 16:27:06 +00:00
2017-04-23 16:01:28 +00:00
### Build options and recompiling
Building all of Retro68 involves building binutils and gcc... twice, so it
takes quite a while.
You can pass the `--no-68k` , `--no-ppc` or `--no-carbon`
flags to `build-toolchain` to limit yourself to the old Macs you're really
interested in (note that `--no-ppc` implies `--no-carbon` ).
After the initial build, you can use the `--skip-thirdparty` option in order to
skip gcc and binutils and just compile the Retro68-specific tools, libraries and
sample programs.
The `build-host` , `build-target` , `build-target-ppc` and `build-target-carbon`
directories are CMake build directories generated from the top-level `CMakeLists.txt` ,
so you can also `cd` to one of these and run `make` separately if you've made changes.
2021-12-08 21:25:19 +00:00
Using Retro68 with Nix
----------------------
2022-08-17 07:56:29 +00:00
If you are not using the [Nix Package Manager ](https://www.nixos.org ), please skip this section. But maybe you should be using it ;-).
2021-12-08 21:25:19 +00:00
Nix is a package manager that runs on Linux and macOS, and NixOS is a Linux distribution based on it.
2023-12-28 20:34:56 +00:00
Try the [Determinate Nix Installer ](https://install.determinate.systems/ ) for the best installation experience.
2021-12-08 21:25:19 +00:00
2023-12-28 20:34:56 +00:00
[TODO: docs on using the binary cache to avoid builds]
2021-12-08 21:25:19 +00:00
2023-12-28 20:34:56 +00:00
Once you've got `nix` installed, and without checking out the Retro68 repository, you can run
nix develop github:autc04/Retro68#m68k
2021-12-08 21:25:19 +00:00
from the Retro68 directory to get a shell with the compiler tools targeting
68K Macs available in the path, and `CC` and other environment variables already
set up for you. You can then `cd` to one of the example directories or to your
own project and use `cmake` to build it.
2023-12-28 20:34:56 +00:00
Likewise, use
nix develop github:autc04/Retro68#powerpc
... to get an environment targeting PowerPC Macs.
2021-12-08 21:25:19 +00:00
2023-12-28 20:34:56 +00:00
If you have a local checkout of Retro68, you can replace `github:autc04/Retro68` by the path
to that local checkout, e.g., run `nix develop .#m68k` from inside the Retro68 directory.
2021-12-08 21:25:19 +00:00
2024-05-01 22:11:49 +00:00
To see how to set up your own nix-based build and development environment for your own application,
head over to the github.com/autc04/Retro68NixSample repository.
2023-12-28 20:34:56 +00:00
You can also use the `nix build` command to build packages. As always with `nix` ,
2021-12-08 21:25:19 +00:00
the result will be somewhere in a subdirectory of `/nix/store` , with a symlink
2023-12-28 20:34:56 +00:00
named `result` placed in the directory where you invoked the command.
| Command | What |
|--------------------------------------------------------------------|-------------------------------------------|
| `nix build github:autc04/Retro68#samples-m68k` | Sample programs for 68K |
| `nix build github:autc04/Retro68#samples-powerpc` | Sample programs for PowerPC |
| `nix build github:autc04/Retro68#pkgsCross.m68k.zlib` | zlib library, cross-compiled for 68K Macs |
| `nix build github:autc04/Retro68#pkgsCross.m68k.` *packagename* | cross-compile *packagename* to 68K |
| `nnix build github:autc04/Retro68#pkgsCross.powerpc.` *packagename* | cross-compile *packagename* to PowerPC |
2021-12-08 21:25:19 +00:00
You can attempt to cross-compile *any* package from the `nixpkgs` collection. Unless the
package contains a very portable library, the command will of course fail. Please don't
report bugs, please report successes instead!
2023-11-12 13:38:53 +00:00
Using Retro68 with Docker
-------------------------
Whenever commits are merged into the Retro68 git repository, a build pipeline is triggered to
create a container image which is then pushed to the Retro68 package repository as
`ghcr.io/autc04/retro68` . This image contains the complete 68K and PPC toolchains ready for
use for either local development or as part of CI pipeline. The command line below shows an
example invocation of Retro68 to build the `Samples/Raytracer` app:
```
$ git clone --depth 1 https://github.com/autc04/Retro68.git
$ cd Retro68
$ docker run --rm -v $(pwd):/root -i ghcr.io/autc04/retro68 /bin/bash < < "EOF"
cd Samples/Raytracer
rm -rf build & & mkdir build & & cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/Retro68-build/toolchain/m68k-apple-macos/cmake/retro68.toolchain.cmake
make
EOF
```
The container image is configured by default to use the multiversal interfaces, but it is
possible to use the universal interfaces by passing a path to either a local file or a URL
that points to a Macbinary DiskCopy image containing the "Interfaces& Libraries" directory
from MPW.
Using the universal interfaces from a local file:
```
$ docker run --rm -v $(pwd):/root -v $(pwd)/MPW-GM.img.bin:/tmp/MPW-GM.img.bin \
-e INTERFACES=universal -e INTERFACESFILE=/tmp/MPW-GM.img.bin \
-i ghcr.io/autc04/retro68 /bin/bash < < "EOF"
cd Samples/Raytracer
rm -rf build & & mkdir build & & cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/Retro68-build/toolchain/m68k-apple-macos/cmake/retro68.toolchain.cmake
make
EOF
```
Using the universal interfaces from a URL:
```
$ docker run --rm -v $(pwd):/root \
-e INTERFACES=universal -e INTERFACESFILE=https://mysite.com/MPW-GM.img.bin \
-i ghcr.io/autc04/retro68 /bin/bash < < "EOF"
cd Samples/Raytracer
rm -rf build & & mkdir build & & cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/Retro68-build/toolchain/m68k-apple-macos/cmake/retro68.toolchain.cmake
make
EOF
```
Note that `entrypoint.sh` checks to see if the universal interfaces are installed into
`/Retro68/toolchain/universal` first before attempting to access the file or URL specified
by INTERFACESFILE. This means that it is possible to use caching or another volume so that
the universal interfaces are only processed once to speed up builds e.g.
```
$ docker run --rm -v $(pwd):/root \
-v $(pwd)/universal:/Retro68-build/toolchain/universal \
-e INTERFACES=universal -e INTERFACESFILE=https://mysite.com/MPW-GM.img.bin \
-i ghcr.io/autc04/retro68 /bin/bash < < "EOF"
cd Samples/Raytracer
rm -rf build & & mkdir build & & cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/Retro68-build/toolchain/m68k-apple-macos/cmake/retro68.toolchain.cmake
make
EOF
```
and then on subsequent runs:
```
$ docker run --rm -v $(pwd):/root \
-v $(pwd)/universal:/Retro68-build/toolchain/universal \
-e INTERFACES=universal \
-i ghcr.io/autc04/retro68 /bin/bash < < "EOF"
cd Samples/Raytracer
rm -rf build & & mkdir build & & cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/Retro68-build/toolchain/m68k-apple-macos/cmake/retro68.toolchain.cmake
make
EOF
```
2012-04-24 01:22:36 +00:00
Sample programs
---------------
2014-10-17 23:36:57 +00:00
Sample programs are built in several formats:
- On Macs: Real Mac Applications (`ApplicationName.APPL`)
- Elsewhere: `ApplicationName.APPL` , `.rsrc/ApplicationName.APPL` , `.finf/ApplicationName.APPL` (BasiliskII/Sheepshaver compatible)
- MacBinary files (`ApplicationName.bin`)
- Raw HFS disk image (`ApplicationName.dsk`, containing `ApplicationName` )
2017-09-23 19:02:22 +00:00
- AppleDouble file pairs (`ApplicationName.ad`, `%ApplicationName.ad` , Executor compatible)
2014-10-17 23:36:57 +00:00
2015-10-07 00:11:44 +00:00
Look under `Retro68-build/build-target/` (68K),
`Retro68-build/build-target-ppc/` (PowerPC Classic) and
2017-10-04 15:34:00 +00:00
`Retro68-build/build-target-carbon/` (PowerPC Carbon) for the compiled examples,
especially under the `Samples` subdirectory.
2012-04-24 01:22:36 +00:00
2015-09-12 22:33:40 +00:00
Components
----------
2012-04-24 01:22:36 +00:00
Retro68 is an aggegation of various existing free software
2015-09-12 22:33:40 +00:00
projects with a few components added.
2012-04-24 01:22:36 +00:00
Third Party Components:
2023-12-29 00:50:49 +00:00
- binutils 2.39
- gcc 12.2.0
- newlib 4.2 (inside the gcc directory)
2017-10-04 14:13:00 +00:00
- libelf from elfutils-0.170
2015-09-12 22:33:40 +00:00
- hfsutils 3.2.6
2012-04-24 01:22:36 +00:00
Retro68-Specific Components:
2015-09-12 22:33:40 +00:00
- ResourceFiles library
- Rez
- PEFTools (MakePEF and MakeImport)
2019-06-23 14:50:09 +00:00
- Elf2Mac
2017-10-04 14:13:00 +00:00
- LaunchAPPL
2012-04-24 01:22:36 +00:00
- libretro
2015-07-16 22:47:29 +00:00
- TestApps - a few tiny test programs
2019-06-23 14:50:09 +00:00
- AutomatedTests
2015-07-16 22:47:29 +00:00
- Sample Programs: Raytracer, HelloWorld, Launcher, Dialog
2012-04-24 01:22:36 +00:00
### binutils
2015-09-12 22:33:40 +00:00
Two new target platforms:
- `m68k-apple-macos` , based on the `m68k-unknown-elf` target
- `powerpc-apple-macos` , based on the `powerpc-ibm-aix` target
The powerpc target has a few hacks to make weak symbols work as expected.
2017-10-04 14:13:00 +00:00
The elf target has a hack to protect MacsBug symbols from -gc-sections.
2012-04-24 01:22:36 +00:00
### gcc
2015-09-12 22:33:40 +00:00
Various patches and hacks:
- New target platforms `m68k-apple-macos` and `powerpc-apple-macos` .
2018-12-19 07:51:54 +00:00
- support `"\pPascal String Literals"`
2015-09-12 22:33:40 +00:00
68K specific:
2012-04-24 01:22:36 +00:00
- Changed register usage.
- Change the way 1-byte and 2-byte parameters are passed.
2014-09-24 23:58:30 +00:00
- added a pascal calling convention (`pascal` or `__attribute__((__pascal__))` )
- added `__attribute__((__raw_inline__(word1, word2, word3)))` to emulate `ONEWORDINLINE` and friends
- added `__attribute__((regparam("...")))` to specify custom register calling conventions
2015-07-16 22:47:29 +00:00
- added `#pragma parameter` to specify custom register calling conventions
2015-08-27 20:13:46 +00:00
- added support for the `= { 0x1234 }` syntax for inline machine code.
2012-04-24 01:22:36 +00:00
2015-10-07 00:11:44 +00:00
PowerPC specific:
- New flag -carbon that makes gcc link with `-lCarbonLib` instead of `-lInterfaceLib`
2012-04-24 01:22:36 +00:00
### newlib
Standard C library. Currently unmodified. The missing platform-dependent
bits haven't been added, instead they are found in 'libretro'.
2017-10-04 14:13:00 +00:00
### libelf
2012-04-24 01:22:36 +00:00
2017-10-04 14:13:00 +00:00
A library for convenient access to ELF files, taken from the elfutils-0.170
package. Or rather, brutally ripped out of it, hacked to compile on non-linux
platforms (< endian.h > is not a standard header file), and made to build with
cmake instead of autotools. Much simpler now.
2012-04-24 01:22:36 +00:00
2018-12-19 07:51:54 +00:00
### hfsutils
2012-04-24 01:22:36 +00:00
2015-09-12 22:33:40 +00:00
No changes.
2012-04-24 01:22:36 +00:00
2015-09-12 22:33:40 +00:00
### ResourceFiles
A C++ Library for manipulating resource forks.
2015-08-27 20:13:46 +00:00
### Rez
2015-08-29 01:33:14 +00:00
A reimplementation of Apple's Rez resource compiler. Reads `.r` files
containing textual resource descriptions and compiles them to binary
resource files.
2015-08-27 20:13:46 +00:00
2017-10-04 14:13:00 +00:00
### Elf2Mac
A wrapper around the linker for 68K programs; it supplies a linker script,
invokes the linker, and converts the resulting ELF binary to a Mac APPL with
one or more segments, or to a flat file which can be converted to a code resource
using Rez.
### LaunchAPPL
A tool for lauching compiled Mac applications via various emulators.
2017-04-23 16:01:28 +00:00
### ConvertObj
Reads a MPW 68K Object file (`*.o`) and converts it to input for the
GNU assembler (`powerpc-apple-macos-as`). Well, as long as the .o file does not
use global variables or non-local function calls. Used to import glue code from
MPW's `Interface.o` library.
2015-09-12 22:33:40 +00:00
### PEFTools
2017-04-23 16:01:28 +00:00
Tools supporting the Apple's PEF format, the Preferred Executable Format
for PowerPC Macs.
- `MakePEF` , a tool to convert xcoff files to PEF.
2015-09-12 22:33:40 +00:00
- `MakeImport` , a tool to create an xcoff import stub library from a PEF-format library.
2015-10-07 00:11:44 +00:00
### prepare-headers.sh:
2017-04-23 16:01:28 +00:00
Apply any necessary patches to Apple's headers.
2015-10-07 00:11:44 +00:00
### ImportLibraries
Import Libraries in XCOFF format. Based on the list of symbols in Apple's import
libraries. Generated using the `MakeImport` tool.
2012-04-24 01:22:36 +00:00
### libretro
2015-09-12 22:33:40 +00:00
Contains startup code (handles relocations on 68K) and implementations
2012-04-24 01:22:36 +00:00
for some standard library functions.
2015-07-16 22:47:29 +00:00
### Console
2012-04-24 01:22:36 +00:00
2015-07-16 22:47:29 +00:00
Contains a library that implements basic text console functionality.
2012-04-24 01:22:36 +00:00
2017-10-04 14:13:00 +00:00
### AutomatedTests
An automated test suite that can be run using `ctest` and `LaunchAPPL` .
2015-07-16 22:47:29 +00:00
### Sample Program: Hello World
The binary is in Retro68-build/build-target/Samples/HelloWorld/.
2012-04-24 01:22:36 +00:00
### Sample Program: Raytracer
Calculates a nice 3D image, pixel by pixel.
2014-09-17 01:39:50 +00:00
There are two versions: raytracer.c is a straightforward
plain C implementation using floating point arithmetic.
2012-04-24 01:22:36 +00:00
2014-09-17 01:39:50 +00:00
Raytracer2 makes use of C++ features; it also uses
2012-04-24 01:22:36 +00:00
fixed point arithmetic instead of floating point
(operator overloading FTW).
2015-07-16 22:47:29 +00:00
The binaries are in Retro68-build/build-target/Samples/Raytracer/.
### Sample Program: Launcher
A utility program for using Retro68 together with the minivmac emulator.
Waits for a disk(image) to be inserted, and if it contains a single application, launches it.
After the application exits, the disk is ejected again.
This way, you can just drag a .dsk file generated by Retro68 on a minivmac Window to run your application.
Intended for System 6 without Multifinder.
### Sample Program: Dialog
Shows a simple and useless dialog box. Demonstrates how to use Rez, the resource compiler.
The binary is in Retro68-build/build-target/Samples/Dialog/.
2018-01-06 02:09:59 +00:00
### Sample Program: WDEF
On the one hand, this is an example for a very basic multi window application with menus and desk accessories.
On the other hand, it shows how to write code resources like WDEF window definition procedures.
2012-04-24 01:22:36 +00:00
2012-04-24 22:54:17 +00:00
License
-------
2017-12-05 20:54:56 +00:00
The original parts of Retro68 are licensed under [GPL3+ ](./COPYING ), as are
2012-04-24 22:54:17 +00:00
most other parts. Some parts are licensed GPL2+ or with more
2017-12-05 20:54:56 +00:00
liberal licenses. The *libretro* runtime library is licensed under GPL3+ with the
GCC runtime exception (see [COPYING.RUNTIME ](./COPYING.RUNTIME ), so there are no licensing restrictions
on programs compiled with Retro68.
Check the copyright notices in the individual files for details.
2017-10-06 23:37:53 +00:00
LaunchAPPL and the Test Suite
-----------------------------
`LaunchAPPL` is a tool included with Retro68 intended to make launching the
2022-03-18 04:10:37 +00:00
compiled Mac applications easier. Its use is optional, so you may skip reading
2017-10-06 23:37:53 +00:00
this section.
Currently, LaunchAPPL supports the following methods for launching Mac applications:
* classic - launch in the Classic environment on PowerPC Macs up to Tiger (10.4)
* carbon - launch as a Carbon app on PowerPC Macs and via Rosetta on Intel Macs up to Snow Leopard (10.6)
* minivmac - launch using the Mini vMac emulator
* executor - launch using Executor
2018-05-02 20:16:32 +00:00
* ssh - Invoke the `LaunchAPPL` tool remotely via ssh
* serial - Connect to a real Mac running the `LaunchAPPLServer` application via a null modem cable
2019-01-22 17:28:44 +00:00
* tcp - Connect to a real Mac running the `LaunchAPPLServer` application via a completely insecure TCP connection
2019-01-23 18:41:12 +00:00
* shared - Communicate with `LaunchAPPLServer` via files in a shared folder
2017-10-06 23:37:53 +00:00
If you're running on a Mac that's old enough to use the `classic` or `carbon` backends,
they will work out of the box, just launch an application as follows
(assuming you've added `Retro68-build/toolchain/bin` to your `PATH` ):
LaunchAPPL -e classic Retro68-build/build-target/Samples/Raytracer/Raytracer2.bin
LaunchAPPL -e carbon Retro68-build/build-target-carbon/Samples/Raytracer/Raytracer2.bin
To specify either environment as a default, or to configure one of the other emulators,
copy the file `Retro68/LaunchAPPL/LaunchAPPL.cfg.example` to `~/.LaunchAPPL.cfg`
and edit to taste (documentation is provided in comments).
**CONTRIBUTION OPPORTUNITY** - This tool can easily be extended with further backends,
2019-01-22 17:28:44 +00:00
so make it work with your favourite emulator. Just add new subclasses for the
2017-10-06 23:37:53 +00:00
`LaunchMethod` and `Launcher` classes, they're documented.
### The Test Suite
2019-11-15 00:22:20 +00:00
The directory `AutomatedTests` contains an automated test suite that runs via
2017-10-06 23:37:53 +00:00
`LaunchAPPL` . It's currently only relevant if you want to hack on the low-level
parts of Retro68.
The test suite will be configured automatically on sufficiently old Macs.
2019-06-23 14:50:09 +00:00
Everywhere else, first configure `LaunchAPPL` (see above).
2017-10-06 23:37:53 +00:00
2019-06-23 14:50:09 +00:00
To run the tests, invoke `ctest` in the `Retro68-build` directory, or in one
of the `build-target` , `build-target-ppc` or `build-target-carbon` directories.
2017-10-06 23:37:53 +00:00
ctest
2019-06-23 14:50:09 +00:00
You can also use the cmake variable `RETRO68_LAUNCH_METHOD` to override the LaunchAPPL default
for specific platforms:
cmake . -DRETRO68_LAUNCH_METHOD=minivmac