Linux Patch

eXoDOS Linux Patch

Overview

The eXoDOS Linux patch is a complete conversion to make all features of eXoDOS work on Linux systems just as they would in Windows. An official Linux frontend, called exogui, is included as part of this conversion. Additionally, the patch is written to ensure that the collection works as expected in dual-boot environments. After the Linux patch is installed, if eXoDOS is updated or games are installed, this will be reflected in both Linux and Windows environments.

As it is encouraged to seed the collection, installing the Linux patch will not alter any torrent files. The patch does not change the existing eXoDOS framework, but instead supplements it.

At this time of this writing, the latest eXoDOS Linux Patch is for version 6.4.

Supported distributions include:

• Arch / Manjaro Linux / SteamOS
• Fedora
• Ubuntu (and Ubuntu-based distributions) / Debian
• Nearly any x86_64 distro that has flatpak support

Unsupported:

• ARM, IBM Power, and RISC-V computers and devices are not supported at this time. This includes the Raspberry Pi. We need someone to volunteer to build ARM versions of the flatpaks for support to be added.
• macOS and BSD are also unsupported at this time. Until we have a volunteer to add macOS support to the frontend, this is unlikely to change. Backend support exists for the eXoDREAMM project, and the backend for eXoDOS has been partially converted in case we get a volunteer.

Installation Process

Step 1 - Extracting Zip Archive

First, the eXoDOS 6.4 Linux Patch.zip file must be extracted to the correct location.

Copy the eXoDOS 6.4 Linux Patch.zip file to the root directory of your freshly downloaded eXoDOS 6.4 collection. (This is where files such as eXoDOS Catalog.pdf and Setup.bat are located)

Then, in your file manager, right click on the eXoDOS 6.4 Linux Patch.zip file and select "Extract Here" or "Extract > Extract archive here", depending on what you are using.

Alternatively, you may open the zip with a utility such as Ark, and drag the files and folders into the root eXoDOS directory.

The important thing is to ensure the files are extracted into the root directory of the collection, and not into a newly created subdirectory.

After this has been done, proceed to the next step.

Step 2 - Installing Dependencies

The next step is to install the software needed to run the collection. The install_dependencies.command script will run you through a guided setup to do this.

Note: If you are using Thunar or XFCE, you will first need to enable running shell files as executables. To do this, open a terminal and run the following command: xfconf-query --channel thunar --property /misc-exec-shell-scripts-by-default --create --type bool --set true

In your file manager, double-click on install_dependencies.command to start the dependency installer. If you are asked whether you want to execute the file, click yes.

If you are using Nautilus or Gnome and are not given this option to run by double-clicking, right click the file and select Run as Program.

Note: This step will need to be done on any Linux computer that has not previously ran eXoDOS 6, even if the full setup has already been completed on a portable drive. Also note that the flatpaks are installed at a user level. As such, other users will need to run the dependency installer separately as well. If you update your video drivers, you may also need to follow that up with a flatpak update. Rerunning a dependency installer installation will handle that for you.

Upon running the dependency installer, you will be prompted with a guided setup that gives the following options:
The "[D]ownload the latest setup" option will only grab the newest version of the eXo Dependency Installer, not eXoDOS itself. This may be useful if there is a problem with the dependency installer or if new flatpaks are needed. If the dependency installer is updated, it should be reran to launch the new version. To proceed with installing the dependencies, choose "[P]roceed with installation" and follow the on-screen instructions.

[P]roceed with installation
[D]ownload the latest setup
[R]emove all installed eXo packages
[A]bort installation

The "[D]ownload the latest setup" option will only grab the newest version of the eXo Dependency Installer, not eXoDOS itself. This may be useful if there is a problem with the dependency installer or if new flatpaks are needed. If the dependency installer is updated, it should be reran to launch the new version.

To proceed with installing the dependencies, choose "[P]roceed with installation" and follow the on-screen instructions.

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).

Using eXoDOS

exogui

A member of our Discord, jelcynek, has currently created a Linux frontend, exogui, which is a fork of Flashpoint Launcher. It is still very much a work in progress, but it has been bundled with eXoDOS. As the frontend improves, newer versions will be included with updates.

Running start-exogui will start the frontend.

The website for exogui can be found at https://github.com/margorski/exodos-launcher/. At this time, jelcynek is looking for volunteers to help in the development of the frontend. If you are interested, please reach out to him in the #linux_port_for_nerds channel of our Discord.

Playing Without Frontend

After downloading the collection, installing the dependencies with install_linux_dependencies.sh, and running Setup.sh, you can play the games in the following way without a frontend:

Navigate to the eXo/eXoDOS/!dos/ directory. Here, you will find 7200 game directories that contain launcher and setup shell files. These files should be executed from a terminal window.

For example, from the root directory of the collection, you could type:

cd eXo/eXoDOS/\!dos/mi2/
bash Monkey\ Island\ 2\ -\ LeChuck\'s\ Revenge\ \(1991\).sh

Note: if you have bash completion enabled, you can press the tab key to make typing name of a script easier.

The first time you attempt to run a game it will ask if you want to install it. Subsequent runs will directly launch the game.

Initial install may take some time depending on the size (a few of these games are upwards of 8 CDs!). During install you will be prompted to choose whether or not to enforce aspect ratio, full screen or windowed mode, and if you would like to apply a scaler. Scalers can smooth pixels, making older pixelated games look a bit more modern. The default setting is normal2x.

If you run the install file a second time, it will ask if you would like to uninstall the game. Choosing "yes" will erase the installed files from your disk, but keep the original ZIP file. You will lose any saved games, high scores, or other settings you have defined since the game was installed. If you choose not to uninstall the game you will get the chance to choose full screen or windowed again and another opportunity to change the scaler. If the scaler refuses to change, you will have to rerun the Setup file in order to extract clean copies of each games conf file.

Creating Desktop Shortcuts

If you would like to create a desktop shortcut to a game, open a plain text editor, such as gedit or kate, and create a file with the .desktop extension and the following contents, making changes as appropriate:

[Desktop Entry]
Exec=x-terminal-emulator -e "/home/username/eXoDOS/eXo/eXoDOS/\\!dos/mi1/Secret\\ of\\ Monkey\\ Island\\,\\ The\\ \\(1990\\).sh"
Icon=/usr/share/icons/monkeyisland_icon.png
Name[EN_US]=Secret of Monkey Island
Name=Secret of Monkey Island
Type=Application

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.

Note: Setup_with_regeneration.sh does not handle the flatpak/native check in the update.sh or update.bat file. The util_linux.zip file is different from util.zip in many ways. This script does not focus on the contents of those files, even if was used to prepare them originally. If regenerate.sh or converter.sh have been updated, please ensure that you have also updated the util_linux.zip file with the newer versions.

The regenerate.sh script first checks that the eXoDOS files are in the correct location in relation to it. Next, it loads the convertScript function into memory, copies the Setup.bat file to Setup_with_regeneration.sh, and converts the newly created file to bash. From here, the script makes several changes to the Setup_with_regeneration.sh file:

1. Any file reference case inconsistencies are fixed, all util.zip references are changed to util_linux.zip, and additionally needed unzip directives are added.
2. Checks are added to the beginning of the script to ensure it is located in the root directory of the eXoDOS collection.
3. Additional code is added to the end of the script to generate Linux versions for all config files and Windows batch files.

All text manipulation for the above steps is done through sed commands. The final step will scare many people away as it involves numerous sed commands within a sed command. This means each line has a great deal of escape sequences.

Here is a code snippet to give an idea of what some of this looks like:

    sed -i -e '$a\
\
clear\
echo "The rest of the setup is automated but could take over an hour."\
echo ""\
cd "$initialDir"\
cd eXo\
echo "Copying scummvm svn application data to Wine."\
[ -e "util/scummvm.ini" ] \&\& wine cmd /c "md %USERPROFILE%\\\AppData\\\Roaming\\\ScummVM" 2>/dev/null\
[ -e "util/scummvm.ini" ] \&\& wine cmd /c "copy .\\\util\\\scummvm.ini %USERPROFILE%\\\AppData\\\Roaming\\\ScummVM\\\scummvm.ini" 2>/dev/null\
\
echo "Fixing zip archive references."\
\
echo "Fixing batch file reference inconsistencies. This may take several minutes."\
[ `ls -1 Update/*.bat 2>/dev/null | wc -w` -gt 0 ] && sed -i -e "s/^goto :eof/goto :end/" Update/*.bat 2>/dev/null\
for file in eXoDOS/\\\!*/*/*.bat eXoDOS/\\\!*/*/*/*.bat Update/*.bat Magazines/*.bat\
do\
    sed -i -e "s/\\.\\\\\\download\\\\\\/.\\\\\\DOWNLOAD\\\\\\/Ig" "$file"\
    sed -i -e "s/exodos\\\\\\/eXoDOS\\\\\\/Ig" "$file"\
    sed -i -e "s/exo\\\\\\/eXo\\\\\\/Ig" "$file"\
    sed -i -e "s/exo\\\\\\update/eXo\\\\\\Update/Ig" "$file"\
    sed -i -e "s/PPMode/PPmode/I" "$file"\
    sed -i -e "s/c\\*\\.rom/C*.ROM/I" "$file"\
    sed -i -e "s/\\.rom/.ROM/I" "$file"\
    sed -i -e "s|mt32\\\\\\soundcanvas\\.sf2|mt32\\\\\\SoundCanvas.sf2|I" "$file"\
    sed -i -e "s/update\\.zip/update_linux.zip/Ig" "$file"\
    sed -i -e "s/ver\\.exo/ver_linux.exo/Ig" "$file"\
    sed -i -e "s/ver\\.txt/ver_linux.txt/Ig" "$file"\
    sed -i -e "/findstr \\/C/ s/\\"%GameName/\\":%GameName/" "$file"\
    sed -i -e "/fullindex=/ s/\\"\\$gamename/\\":\\$gamename/" "$file"\
done\
echo "Creating game shell files."\
echo "Preparing files for conversion..."\
for file in eXoDOS/\\\!*/*/*.bat eXoDOS/\\\!*/*/*/*.bat Update/*.bat Magazines/*.bat\
do\
    cp "$file" "${file%.bat}.sh"\
done\
chmod +x eXoDOS/\\\!*/*/*.sh\
chmod +x eXoDOS/\\\!*/*/*/*.sh\
chmod +x Update/*.sh\
chmod +x Magazines/*.sh\
\
echo "Creating Linux configuration references. Please wait."\
for file in eXoDOS/\\!*/*/install.sh\
do\
    sed -i -e "s/^\\(.*\\)\\.bat\\(.*\\)/&\\n\\1.sh\\2/" "$file"\
done\

In short, when the Setup_with_regeneration.sh script is executed, the code added to the bottom does the following:

1. Copies the ScummVM SVN application data to Wine
2. Fixes zip archive references
3. Fixes batch file reference inconsistencies
4. Creates shell files
5. Makes shell files executable
6. Prepares shell files for conversion
7. Adds Linux configuration references to Linux game setups
8. Adds Linux configuration references to Windows game setups
9. Adds Linux configuration references to Linux game and magazine launchers
10. Adds Windows configuration references to Linux game setups
11. Converts syntax for the Linux shell files from Windows batch to bash
12. Fixes dosbox.conf typos with known solutions
13. Fixes dosbox.conf file and directory reference inconsistencies
14. Creates DOSBox configuration files for Linux
15. Makes necessary changes to Linux configuration files
16. Applies game specific fixes to Linux files

Note: All of the inconsistency fixes and game specific changes are manually added to the regenerate.sh script. There is no magic voodoo code to determine what needs to be changed to make each game work correctly.

Note on Updates

IMPORTANT: If preparing a full copy of the eXoDOS Linux patch, any existing eXoDOS update files should be considered before packaging the files for final release. The initial eXoDOS 5 Linux patch included the eXoDOS 5.1 update. For completeness as well as the convenience of anyone installing the Linux patch without an active Internet connection, any new versions of exodos5-linux-patch.zip should always include the latest updates. At the same time, a cumulative update patch file, update_linux.zip, is also maintained for people that would like to simply update their already installed version of eXoDOS 5. The details of how the update works will be discussed later. However, it should be noted that both the exodos5-linux-patch.zip file as well as update_linux.zip should contain the latest versions of everything at their time of release.

In the exodos5-linux-patch.zip file, any cumulative updates for bat, conf, and sh files are merged into the Content/!DOSmetadata_linux.zip and Content/Magazines_linux.zip files, overwriting the ones from the eXoDOS 5.0 release. Updates to game archives, on the other hand, are included in the eXo/util/update_linux.zip file.

CAUTION: The update_linux.zip file hosted online is for cumulative updates and is different than the eXo/util/update_linux.zip file contained in the full release of the Linux patch. Any references in this document to the two files can be differentiated by the presence or absence of eXo/util/.

Preparing For Manual Conversion

1. to do

Packaging Files For Release

1. to do along with numerous other sections