Linux Patch

eXoDOS Linux Patch

Overview

The eXoDOS Linux patch is an attempt to make all features of eXoDOS work on Linux systems just as they would in Windows. As a Linux alternative to LaunchBox, a game launcher called exogui is bundled with the patch. Additionally, the patch is written to ensure that the collection works as expected in dualboot environments. After the Linux patch is installed, if eXoDOS is updated, games are installed, or game options are modified, the changes will be reflected in both Linux and Windows environments.

Installing the Linux patch will replace existing Windows batch files with modified versions as well as add additional Linux specific files. It also switches eXoDOS to the Linux update branch. Our team must test and merge any new upstream eXoDOS patches into the Linux branch before they will become available. In addition, there may be updates released for the Linux branch without a corresponding one in the main branch.

Having said that, installing the Linux patch or any updates will not affect any files in the torrent. You will continue to be able to seed the collection.

At this time of this writing, the latest release of the eXoDOS Linux Patch is compatible with eXoDOS 5.

Installation Process

Step 1 - Extracting Zip Archive

First, the exodos5-linux-patch.zip file must be extracted to the correct location.

Copy the exodos5-linux-patch.zip file to the root directory of your freshly downloaded eXoDOS 5 collection. (This is where files such as eXoDOS Catalog.pdf and Setup.bat are located)

Then, in your file manager, right click on the exodos5-linux-patch.zip file and select "Extract Here" or "Extract > Extract archive here", depending on what you are using.

Alternatively, you may open a terminal in that directory, and run the following command:

unzip -o exodos5-linux-patch.zip

After this has been done, installing the collection still requires two more steps, which can be done either in exogui or from a terminal. If you do these steps in exogui, you will need to close and restart it after the installation has been completed.

Step 2 - Installing Dependencies

The next step is to install the software needed to run the collection.

If you want to do this through exogui, double-click on start-exogui. (If exogui fails to start, consult the troubleshooting section of the readme)

Then, select "Install dependencies" in the exogui home tab. Alternatively, you may run this same setup by executing install_linux_dependencies.sh from a terminal window.

Note that this step will need to be done on any computers that have not previously ran eXoDOS 5, even if the full setup has been ran on a portable drive.

The install_linux_dependencies.sh script will run a guided setup to install the needed software.

Officially supported distributions include:

• Debian
• Fedora
• Ubuntu (and Ubuntu-based distributions)
• Arch / Manjaro Linux.

Updates will be periodically released to ensure that compatibility is maintained as newer distributions come out. Simply choose the update menu option to grab the newest version of the setup.

If you would like to request support for your distro to be added, feel free to reach out in the #linux_port_for_nerds channel of our Discord.

When running this setup, you will be given an option to choose between flatpaks and native DOSBox packages. There are some advantages and disadvantages of each.

Flatpaks: Flatpaks have an advantage over native DOSBox packages in that they are more portable. If you are using an unsupported distribution, they will make it much easier to get the collection working. However, our tests have shown that some computers (not most) have distorted FluidSynth output in ECE when using flatpaks.

Native Packages: Native packages do not have this issue, but must be regularly maintained and updated as newer distributions come out. Upgrading your version of Linux may break a previously installed native package. We will occasionally release updates to ensure compatibility is maintained.

Step 3 - Installing eXoDOS

The final step is to run the eXoDOS Setup.

To do this through exogui, select "eXoDOS Setup" on the home tab. Alternatively, you may run Setup.sh from a terminal window.

This will unpack the required eXoDOS files, including the LaunchBox assets and the games front end assets/configs to run the collection. In addition, it will extract the Linux game launcher and setup files. It will make the collection work on both Windows and Linux computers and ensure updates work correctly for both operating systems.

Do not extract these files manually. They are location sensitive.

The eXoDOS Setup will give you the opportunity to customize your set. This includes the option to remove Adult games from the exogui and LaunchBox menu. This removes games with sex or nudity from the LaunchBox XML file. This does not remove violent games. Please make use of the ratings category in LaunchBox if you would like to filter the games further.

You will also be prompted as to if you would like your global defaults to be Fullscreen or Windowed and whether or not you would like to default to Aspect Ratio On or Off. If you choose windowed mode, you will have the option between 640x480 or 1280x960.

Once it is complete, you may either launch the game shell files directly or run exogui to dive right in.

The eXoDOS collection can be run from any directory, as all launch files are designed to use relative paths to each other. Note, however, if you choose to add a desktop shortcut to exogui and then later move eXoDOS to a new location, you will need to rerun the setup to update the shortcut. Note that the setup gives an option to reconfigure previous installations of eXoDOS rather than running through the entire setup process over again.

Important Note

• DO NOT RUN the main Windows Setup.bat file after installing the Linux patch. It will undo the changes necessary for Linux compatibility.
• Running the Setup.sh installation on an eXoDOS instance that was previously installed in Windows will clear the Windows installed games playlist in LaunchBox (due to LaunchBox being reinstalled).

Changelog

Changes to Version 5.1.linux1

Utilities:

• Removed All-Seeing Eye 3 from Linux menu option (map tracking inaccurate)

Games:

• 120 Degree Below Zero (2012) - Changed launcher to use ScummVM (sciAudio.exe not an option for Linux)
• Eye of the Beholder III - Assault on Myth Drannor (1993) - Replaced patched AESOP.EXE file with original (patched exe does not run properly in Linux)
• LockerGnome Quest Redux (2012) - Changed launcher to use ScummVM (sciAudio.exe not an option for Linux)

Files

exodos5-linux-patch.zip

exodos5-linux-patch.zip contains the following files and directories:

├── Content
│   ├── !DOSmetadata_linux.zip
│   └── Magazines_linux.zip
├── eXo
│   └── util
│       └── util_linux.zip
├── eXoDOS Linux ReadMe.txt
├── exogui
│   └── [exogui files]
├── install_linux_dependencies.sh
├── Setup.sh
└── start-exogui

This builds upon the existing file and directory structure of eXoDOS.

• Content/!DOSmetadata_linux.zip - This contains DOSBox configuration files as well as the launcher and setup files (conf, sh, bat) for games; Note these files are also updated to have the content for Version 5.1.linux1.
• Content/Magazines_linux.zip - This contains DOSBox configuration files as well as the launcher and setup files (conf, sh, bat) for disk magazines.
• eXo/util/util_linux.zip - This contains utilities needed to run eXoDOS. Note that several internal files are different than the ones in util.zip, despite having the same filenames.
• exogui - This directory contains the files needed to run exogui.
• install_linux_dependencies.sh - This guided setup script installs the Linux dependencies needed for eXoDOS.
• Setup.sh - This guided setup script installs the eXoDOS collection for Linux.
• start-exodus - This launches the Linux eXoDOS frontend, exogui.

util_linux.zip

util_linux.zip contents:

• aria.zip - Same as in eXoDOS 5 Lite torrent.
• ASE3.zip - Same as in eXoDOS 5.1 update.
• ASE.zip - Same file as in eXoDOS 5.1 update.
• BRC32.exe - Same as in eXoDOS 5 torrent.
• CHOICE.EXE - Same as in eXoDOS 5 torrent.
• converter.sh - Script to assist in the development of the Linux patch; converts batch files to bash shell scripts for Linux.
• deprotect.zip - Same as in eXoDOS 5 torrent.
• dos2unix.exe - Added to eXoDOS Linux patch to ensure configuration changes in Windows do not add carriage returns.
• dosbox.zip - Modified for eXoDOS Linux patch to include Linux conf files.
• GBC.zip - Same as in eXoDOS 5.1 update.
• LinuxPackages.zip - Contains Linux DOSBox packages needed for eXoDOS.
• mt32.zip - Same as in eXoDOS 5 torrent.
• regenerate.sh - Development tool that attempts to convert Windows eXoDOS Setup.bat file into a Linux shell script, which upon being executed will run through the installation and then systematically convert all files to work with Linux.
• scummvm.ini - Same as in eXoDOS 5 torrent.
• scummvm.zip - Same as in eXoDOS 5 torrent.
• SetConsole.exe - Same as in eXoDOS 5 torrent.
• SHADERS.zip - Same as in eXoDOS 5 torrent.
• ssr.exe - Same as in eXoDOS 5 torrent.
• Ultimapper5.zip - Same as in eXoDOS 5.1 update.
• update_linux.zip - Linux branch update files; Linux bash files added and Windows batch files modified; changelog.txt and ver_linux.txt are used to track Linux branch; 5.1 game patch zips also included; Note the EOB3 executable (AESOP.EXE) was reverted to the 5.0 version for Linux compatibility.

Custom Scripts

Note: For the rest of this document, files will be described using their locations after installing eXoDOS.

The following files are not simply handled by the conversion script, but have custom modifications:

• eXo/Update/update.bat
• eXo/Update/update.sh
• eXo/Update/update_installed.sh
• Setup.sh

eXo/util/converter.sh

The converter.sh script contains the convertScript function, which, when called, will attempt to convert a file's batch code to bash. The file that the convertScript function is ran against is determined by a variable, $currentScript. Note that the converter.sh script is not meant to be executed directly.

To prevent direct execution, the converter.sh script checks that a variable, $hideMessage, has a value of true. Note that even when $hideMessage = true, executing converter.sh does not automatically call the convertScript function. Instead, the source command should be ran against converter.sh to bring the convertScript function into the shell session's memory. Then, assuming the value of $currentScript has been set, the convertScript function should be called.

Example use where bat files in a directory called filesToConvert:

hideMessage='true'
. eXo/util/converter.sh
for file in filesToConvert/*.bat
do
    cp "$file" "${file%.bat}.sh"
done
chmod +x filesToConvert/*.sh
for currentScript in filesToConvert/*.sh
do
    convertScript
done

Normally, the converter.sh script is called by the regenerate.sh script and the Setup_with_regeneration.sh script it creates. Details about those scripts will be described later in this document.

convertScript Function

The convertScript function runs a series of sed and Perl commands to convert a file from batch to bash. As this is a very complex text manipulation process, the order of each command is critically important. It is heavily recommended to add any new commands at the bottom of the function. Each subsequent text manipulation command may search for and change something that was previously altered. If any existing text manipulation commands are changed, everything needs to be very carefully audited. Edge cases are everywhere.

Example code snippet from the convertScript function:

    #escape backslashes in all echoes, change \ to / after the redirects
    sed -i -e '/^echo.*\\/{
                   s|#|##|g;
                   s|\\|/#|g;
                   :a;
                   s|^\(echo.*>.*\)/#\(.*\)|\1/\2|;
                   ta;
                   s|/#|\\\\|g;
                   s|##|#|g;
               }' "$currentScript"

    #escape quotes on echoes without redirects
    sed -i -e "/^echo/{ />/! s/\"/\\\\\"/g }" "$currentScript"
               
    #add a double quote to the beginning of echoes
    sed -i -e "s/^echo /echo \"/" "$currentScript"
    
    #add a double quote to the end of echoes without redirects
    sed -i -e "/^echo/{ />/!s/.$/\"/ }" "$currentScript"
    
    #ensure echo redirects are preceded by spaces
    sed -i -e "/^echo/ {/[^[:space:]]>>/ s/>>/ >>/;}" "$currentScript"
    sed -i -e "/^echo.*[^[:space:]]>/{ />>/! s/>/ >/;}" "$currentScript" 
    
    #add a double quote to the end of echoes with redirects
    sed -i -e "/^echo/ s/ >>/\" >> /" "$currentScript"
    sed -i -e "/^echo.*>/{ />>/! s/ >/\" > /;}" "$currentScript"
    
    #escape all $ characters
    sed -i -e "s/\\$/\\\\$/g" "$currentScript"
    
    #make all occurrences of goto lowercase except on echo and comment lines
    sed -i -e '/^echo\|^#/!s/goto/goto/gI' "$currentScript"
    
    #change all occurrences of GOTO to goto only after echo redirections
    sed -i -e '/^echo.*>.*GOTO/ {
                   s/#/##/g;
                   s/GOTO/goto#/g;
                   :a;
                   s/^\(echo.*>.*\)goto#\(.*\)/\1goto\2/;
                   ta;
                   s/goto#/GOTO/g;
                   s/##/#/g;
               }' "$currentScript"

As shown in the above code snippet, comments are used to tell what every text manipulation operation does. This is necessary to ensure that the script continues to be maintainable.

Note: When doing a systematic conversion of the eXoDOS collection, it is important to remember that the convertScript function is ran against every batch file in eXoDOS, with the exception of those in game archives (e.g. run.bat). Additional game specific text manipulations are written in the regenerate.sh script.

eXo/util/regenerate.sh

The purpose of the regenerate.sh script is to assist in the development of future Linux patches by automating the conversion of config files and Windows batch files to Linux compatible bash files. It creates a Setup_with_regeneration.sh file in the root directory of the eXoDOS collection. By executing the Setup_with_regeneration.sh script, a converted eXoDOS setup will run followed by conversion operations to prepare the rest of the collection for the creation of a Linux patch. This script is not intended for end-users. As new versions of eXoDOS come out, both the regenerate.sh script as well as the converter.sh will need to be altered. It is impossible to predict how the Windows batch files will be written. It is very common for eXo to do some extremely complex operations in batch files that can make updating these scripts very challenging.