From ed0b24a6ad74257d19e1c61cf260fa5f503cb710 Mon Sep 17 00:00:00 2001 From: Wolfgang Thaller Date: Sat, 7 Oct 2017 01:37:53 +0200 Subject: [PATCH] improve documentation --- LaunchAPPL/LaunchMethod.h | 45 +++++++++++++++++++++++++++++ LaunchAPPL/Launcher.h | 49 +++++++++++++++++++++++++++++-- README.md | 61 ++++++++++++++++++++++++++++++++------- 3 files changed, 142 insertions(+), 13 deletions(-) diff --git a/LaunchAPPL/LaunchMethod.h b/LaunchAPPL/LaunchMethod.h index bcbf69742c..c8606b4bc3 100644 --- a/LaunchAPPL/LaunchMethod.h +++ b/LaunchAPPL/LaunchMethod.h @@ -9,6 +9,12 @@ class Launcher; +/** + * @brief The LaunchMethod class + * + * To add a new backend to LaunchAPPL, start by subclassing this + * and updating RegisterLaunchMethods() in LaunchAPPL.cc. + */ class LaunchMethod { public: @@ -18,15 +24,54 @@ public: LaunchMethod(); virtual ~LaunchMethod(); + /** + * @brief GetName + * @return the name of the launch method, as it will be specified on the command line + */ virtual std::string GetName() = 0; + + /** + * @brief GetOptions + * @param desc + * + * Add any command line options for this LaunchMethod + * to the options_description structure. + */ virtual void GetOptions(options_description& desc); + /** + * @brief CheckPlatform + * + * Check whether this is the right kind of machine to use this method. + * For things like Apple's Classic Environment, which is only available on some system versions. + * The default implementation returns true. + */ virtual bool CheckPlatform(); + + /** + * @brief CheckOptions + * @param options + * @return are we ready to run? + * + * Check whether all necessary options have been specified. + * Don't output error messages here, this is also called when outputting usage information + */ virtual bool CheckOptions(variables_map& options); + /** + * @brief MakeLauncher + * @param options + * @return a new instance of a subclass of Launcher which will do the actual work + */ virtual std::unique_ptr MakeLauncher(variables_map& options) = 0; protected: + + /** + * @brief CheckExecutable + * @param program + * @return true if "program" exists in the $PATH and is executable. + */ bool CheckExecutable(std::string program); }; diff --git a/LaunchAPPL/Launcher.h b/LaunchAPPL/Launcher.h index e6bf703725..5c8a66fec8 100644 --- a/LaunchAPPL/Launcher.h +++ b/LaunchAPPL/Launcher.h @@ -5,6 +5,12 @@ #include "ResourceFile.h" #include +/** + * @brief The Launcher class + * + * Subclasses are instantiated by the corresponding LaunchMethod subclasses. + */ + class Launcher { protected: @@ -16,16 +22,55 @@ protected: int ChildProcess(std::string program, std::vector args, int timeout); public: + /** + * @brief Launcher + * @param options + * + * Create a Launcher object and set up a temporary directory to play in. + * Reads the Applicatio specified on the command line into the `app` member variable. + * Also create an empty file named 'out' in the temporary directory, for test suite programs. + */ Launcher(boost::program_options::variables_map& options); + + /** + * @brief Launcher + * @param options + * @param f + * + * Create a Launcher object, set up a temporary directory + * and store the application to be executed at `appPath` in the temporary directory, + * using format `f`. + */ Launcher(boost::program_options::variables_map& options, ResourceFile::Format f); - void KeepTempFiles() { keepTempFiles = true; } + /** + * @brief ~Launcher + * Delete our temporary directory. + */ + virtual ~Launcher(); + + /** + * @brief Go + * @param timeout + * @return true for success + * + * Launch the application, return true on success and false on error or timeout. + */ virtual bool Go(int timeout = 0) = 0; + /** + * @brief DumpOutput + * + * After the application has been run, copy the contents of the 'out' file to stdout. + */ virtual void DumpOutput(); - virtual ~Launcher(); + /** + * @brief KeepTempFiles + * Inhibit deletion of the temporary directory. + */ + void KeepTempFiles() { keepTempFiles = true; } }; #endif // LAUNCHER_H diff --git a/README.md b/README.md index 5325cbb324..d5f815e60b 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,8 @@ of the Retro68 directory: ../Retro68/build-toolchain.bash The toolchain will be installed in the "toolchain" directory inside -the build directory. +the build directory. All the commands are in `toolchain/bin`, so you might want +to add that to your `PATH`. If you're building this on a PowerMac running Mac OS X 10.4, tell the build script to use the gcc you've installed via tigerbrew: @@ -100,7 +101,6 @@ 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. - Sample programs --------------- @@ -203,15 +203,6 @@ using Rez. ### LaunchAPPL A tool for lauching compiled Mac applications via various emulators. -Currently, there are the following backends: - -* 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 - -**CONTRIBUTION OPPORTUNITY** - This tool can easily be extended with further backends, -so make it work with your favourtite emulator. ### ConvertObj @@ -295,3 +286,51 @@ The original parts of Retro68 are licensed under GPL3+, as are most other parts. Some parts are licensed GPL2+ or with more liberal licenses. Check the copyright notices in the individual files. + + + + +LaunchAPPL and the Test Suite +----------------------------- + +`LaunchAPPL` is a tool included with Retro68 intended to make launching the +compiled Mac applications easier. It's use is optional, so you may skip reading +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 + +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, +so make it work with your favourtite emulator. Just add new subclasses for the +`LaunchMethod` and `Launcher` classes, they're documented. + +### The Test Suite + +The directory `AutomatedTests` contains an autonated test suite that runs via +`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. +Everywhere else, first configure `LaunchAPPL` (see above) and then: + + cs Retro68-build/build-target + cmake . -DRETRO68_LAUNCH_METHOD=minivmac # or executor, ... + make + +To run the tests, invoke `ctest` in the `build-target` directory. + ctest