commit a70befad3b75655eb6e51db75974b71eb3e3dedf Author: gryf Date: Sun Dec 18 20:42:04 2016 +0100 Initial commit diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..710e6bb --- /dev/null +++ b/LICENSE @@ -0,0 +1,24 @@ +Copyright (c) 2016, Roman Dobosz +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + * Neither the name of the organization nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL ROMAN DOBOSZ BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..eddc0f1 --- /dev/null +++ b/README.rst @@ -0,0 +1,136 @@ +============== +FS-UAE Wrapper +============== + +This little utility is a wrapper on great FS-UAE_ emulator, to perform some +actions, like uncompressing archived files (CD ROMs images, filesystems), +launch the emulator and archive emulator save state. + +As an example, if there is a collection of CD³² game files and one want to +provide configuration for each game, but want to keep ISO images with +corresponding files in archive (due to size of those images) than FS-UAE +Wrapper is a way to achieve this. + +Requirements +============ + +- Python (2 or 3) +- `7z`_ archiver +- `unrar`_ + +Installation +============ + +Just perform (preferably in ``virtualenv``) a command: + +.. code:: shell-session + + $ pip install fs-uae-wrapper + +Usage +===== + +After installation you should be able to access new command +``fs-uae-wrapper``, and its invocation is identical like ``fs-uae`` binary: + +.. code:: shell-session + + $ fs-uae-wrapper [fs-uae-config-file] [parameters] + +There is special option for passing wrapping module, which might be placed +directly in fs-uae configuration or passed as an option: + +.. code:: ini + + [config] + ... + wrapper = cd32 + ... + +or + +.. code:: shell-session + + $ fs-uae-wrapper --wrapper=cd32 + +In this case there would several things happen. First, ``Config.fs-uae`` would +be searched, read and there would be ``wrapper`` option searched. If found, +specific module will be loaded and depending on the module, there would be +performed specific tasks before ``fs-uae`` is launched and after it. + +Assumption is, that configuration file are written in portable way, so the are +saved as `relative configuration file`_ (hence the name ``Config.fs-uae``, even +if the are named differently. If certain wrapper is specified, it will create +temporary directory and place the configuration file there as +``Config.fs-uae``. + +If no ``wrapper`` option would be passed either as an config option or +command line argument, all command line options will be passed to the fs-uae +executable as-is. + +Modules +======= + +For now, only for ``cd32`` module exists, but there are planned couple more. + +cd32 +---- + +There are few assumptions regarding file names and archives. Let's see some +sample config for a game, which is saved as ``ChaosEngine.fs-uae``: + +.. code:: ini + :number-lines: + + [config] + wrapper = cd32 + + amiga_model = CD32 + title = The Chaos Engine CD32 + + cdrom_drive_0 = Chaos Engine, The (1994)(Renegade)(M4)[!][CDD3445].cue + + save_states_dir = $CONFIG/fs-uae-save/ + + joystick_port_1_mode = cd32 gamepad + platform = cd32 + +First assumption is that archive containing files for the game (here: *Chaos +Engine*) should not be in subdirectory. Second, archive name should be the same +as a cue file, so in this case it should be like ``Chaos Engine, The +(1994)(Renegade)(M4)[!][CDD3445].zip`` in case of zip archive. There are three +archive types supported: 7z, rar and zip. + +Next, the invocation of the wrapper would be as follows: + +.. code:: shell-session + + $ fs-uae-wrapper ChaosEngine.fs-uae + +Now, there several thing will happen: + +- Config file will be read, and wrapper module will be find (because we already + put it on line 2) +- New temporary directory will be created +- Archive with game assists will be extracted in that directory +- Configuration file will be copied into that directory, and renamed to + ``Config.fs-uae`` +- If there is saved state, it also would be extracted there +- ``fs-uae`` will be launched inside that directory + +Next, after ``fs-uae`` quit, there will: + +- Create archive containing save state with name like the configuration file + with additional ``_save`` suffix. In this example it would be + ``ChaosEngine_save.7z``. +- Wipe out temporary directory + +License +======= + +This work is licensed on 3-clause BSD license. See LICENSE file for details. + +.. _FS-UAE: https://fs-uae.net/ +.. _relative configuration file: https://fs-uae.net/configuration-files +.. _unrar: http://www.rarlab.com/rar_add.htm +.. _7z: http://p7zip.sourceforge.net/