Dolmades are intended as a mean to ease packaging, installation, usage and distribution of Windows applications in Linux environments to the utmost extent. A dolma is a containerized Windows app which runs on Linux without external dependencies.
Usage
Development:
The focus of the v1.x release cycle will be put on support for latest vanilla wine stable and staging, the standardization of the recipe specification used to create dolmades, proper ingredients handling, the protoypical implementation of the basic concepts and the completion of major unresolved issues.
The current prototypical implementation is done in form of the following Python scripts:
dolmades
- to maintain your installed windows applicationscook
- cooks a dolma given a recipe and its ingredientsbox
- creates a standalone installer from a cooked dolmagoglizer
- creates template recipes for win-only GOG games; GOG account requiredconfig.py
- a configuration file providing important settingsOnce the prototype is feature-complete I want to work on an enhanced version based on Qt and a remote repository service where user can store their dolmades, ingredients and recipes.
Dolmades make use of the following underlying technologies:
v1.2.1
v1.2 "Soap-free Cleanser"
dolmades help
subcommanddolmades export
reproduciblev1.1 "From Blue To Green"
v1.0 "The Goglizer" - 2018-11-27
Dolmades makes use of several concepts which will be briefly explained here:
Either download the release tar ball
curl -L -o dolmades.tgz https://github.com/dolmades/dolmades-cli/archive/v1.2.tar.gz
tar -xzf dolmades.tgz
cd dolmades-cli-1.2/
or simply clone it using git:
git clone -b "v1.2" --single-branch --depth 1 https://github.com/dolmades/dolmades-cli.git
cd dolmades-cli
Cooking describes the process of building a dolma from a recipe given its required ingredients. To cook a dolma use the very simple example:
./cook recipes/ASD_LifeForce.dolma
This will install the winning demo of Assembly 2007 by Andromeda Software Development. At first the required ingredients will be downloaded and verified by its checksum. Next, the dolmade is created and the installation as defined in the recipe is being performed. Finally, you can run the installed dolmade:
./dolmades launch LifeForce_ASD
The dolma can now be uninstalled again:
./dolmades del LifeForce_ASD
Now a second example: the free (as in beer) adventure game "Broken Sword":
./cook recipes/Broken_Sword.dolma --serve
This will create the dolma and add menu entries and a desktop symbol.
./cook launch Broken_Sword
A launcher will appear and offer you multiple choices created by the installer.
Select Windowed Mode
and click "Ok":
The game will be started. You should be hearing sound unless wine detects the wrong alsa device which still may happen on some hardware.
A system tray icon indicates the running dolmade. On left click you can access the run log, on right click you can forcibly terminate the running dolma in case it hangs. The dolma can be removed via the corresponding menu entry.
More recipes for dolmades can be downloaded here
For this to work you'll need to be registered at GOG. They offer some items for free so you can actually test goglizer
without purchasing a game. If you have not done so already obtain the free item "Flight of the Amazon Queen" and verify that it is shown in your personal game collection. Retrieve a list of your games using the script goglizer
:
./goglizer -u
The -u
parameter tells goglizer
to retrieve the dolmades runtime container and your personal game list.
At first, you will be asked to authorize using your GOG account. Since two-factor-authentication is mandatory you will need to check your email and enter the code that GOG has sent to you. This needs to be done only once since the authorization credentials are being stored in your home directory for subsequent use.
Finally, a list of your games is displayed:
Found dolmades repo under /home/stefan/.dolmades/repo
Pulling dolmades runtime container...
da4bf27d-3bf2-3436-916a-e1bc83098523
done
Fetching detailed info about games from GOG...
Retrieving detailed linux game list...
Getting game names (1/1) 48 / 48
Getting game info 26 / 26
Retrieving detailed linux/windows game list...
Getting game names (1/1) 48 / 48
Getting game info 48 / 48
Retrieving detailed windows game list...
Getting game names (1/1) 48 / 48
Getting game info 48 / 48
done!
Windows games available on this account which have no linux installer available
broken_sword_3__the_sleeping_dragon
...
flight_of_the_amazon_queen
...
Note, that only games are listed that have no linux installer. If you want linux games to be listed as well you need to use the -l
parameter:
./goglizer -l
Found dolmades repo under /home/stefan/.dolmades/repo
Windows games available on this account (bold: no linux installer available)
akalabeth_world_of_doom
beneath_a_steel_sky
broken_sword_2__the_smoking_mirror
broken_sword_3__the_sleeping_dragon
...
Now choose a game of your liking and instruct goglizer
to download the ingredients and create a corresponding recipe template using the -d
parameter:
./goglizer -d=flight_of_the_amazon_queen
Now the dolma can be installed:
./cook "flight_of_the_amazon_queen:en:1.1.dolma" --serve
After successful completion you will find a clickable icon on your desktop and a menu entry :)
You can skip the goglizer
run completely by using the recipe under recipes/flight_of_the_amazon_queen:en:1.1.dolma
.
As of now for one out of two games the installation procedure fails or the installed game won't work properly. If that happens dolmades makes it easy to find and apply fixes to the generated recipe. Let's give an real example:
./goglizer -d=edna_harvey_the_breakout
We try to cook it:
./cook edna_harvey_the_breakout:en.dolma
The java installation will fail and leave a broken dolma. First, we need to figure out interactively what needs to be done:
./dolmades debug edna_harvey_the_breakout:en.dolma
> # THIS IS THE REQUIRED FIX: set windows version to WinXP
> winetricks winxp
> # rerun installer and ensure that it works now
> /install/setup_edna_and_harvey_the_breakout_2.1.0.5.exe
# test cooked dolmade, start in windowed mode
targetSelector
The previous changes are now applied permanently to the dolma but will get lost if it will be recooked.
That is why we ought to update the corresponing recipe to include that fix.
Edit edna_harvey_the_breakout:en.dolma
and add the following section right before the RunUser
command which launches the installer using wine
:
RunUser
winetricks winxp
Finally, the dolma can be cooked once more:
./cook edna_harvey_the_breakout:en.dolma
This erases the previous dolma and helps keeping recipe and cooked dolma in sync with each other.
Once a dolma has been cooked and thoroughly tested it is possible to convert it into a standalone installer:
./box LifeForce_ASD
This will package all dependencies and create an offline installer script based on makeself
which installs on various Linux systems without special privileges.
The approximate size overhead produced by the Ubuntu Base Image and the wineprefix will be 800Mb.
Users who download this file should open a terminal at the location of the downloaded file and run the installer like this:
sh LifeForce_ASD.dma.sh
After accepting the license the dolma will be installed under $HOME/Dolmades-v1.1/LifeForce_ASD
. It can then be launched or removed again from the created menu entry or the desktop symbol.
Note: as of now self-installable dolmades will require Python 2.7 and curl on the host system. A future release will probably get rid of this requirement.
Your dolmades are managed by dolmades
Lists the locally available dolmades:
./dolmades list
Removes the given dolma (data, menu entries and desktop symbols) and frees up the allocated space:
./dolmades del name-of-dolma
You can pass multiple dolma names or sha256 container ids.
Executes the /.dolmades/start.sh
script which either runs the executable defined via SetTarget
in the dolmafile
or the target selector script which lets you choose between all installed targets.
./dolmades launch name-of-dolma
It is possible to launch a bash inside the container.
The installation directory will be available under /install
and installed windows applications under /wineprefix
.
Furthermore, the home directory of the calling user is available:
./dolmades debug name-of-dolma
ls -lad $HOME /wineprefix /install
In rare cases you might want to run as fake root, e.g. to install a missing package:
./dolmades root-debug runtime
apt-get update && apt-get -y install vim
If name-of-dolma
is given as argument the changes are being applied permanently.
If name-of-base
is given as argument a temporary dolma is being created and destroyed after the shell is being closed. name-of-base
is used as template and currently can be one of the following:
runtime
- used internally by dolmades
, cook
and goglizer
base
- Ubuntu 18.04 LTS prepared for the installation of winewinestable
- base
with wine stable added and preconfiguredwinedevel
- base
with wine testing added and preconfiguredIt is possible to make files or directories of the host file system accessible from within the container by defining so-called binds. These will apply just when a dolma is being launched but not when it is being debugged. Usually it is sufficient to use the predefined default binds in the recipe.
./dolmades rebind name-of-dolma
# reset the binds as defined in the recipe
# this command is performed during the cooking procedure
./dolmades binds name-of-dolma
# listing the currently configured binds
./dolmades bind name-of-dolma bind1 bind2 ...
A bind is defined using absolute path names as follows: /dolmadedir/dolmadefile:/hostdir/hostfile
or /dolmadedir/:/hostdir/
Use this way to set binds just for tests as they are temporary and will not persist when a dolma is being exported and imported subsequently.
Generally define the binds in your recipe where they will persist over imports/exports.
Notes
/wineprefix/drive_e:/my/hostdir/
to bind to drive E.config.py
predefines a certain set of binds which can be enabled by default. These will allocate some more driver letters starting from Y in reverse.dolmades export
will not change depending on configured binds whereas the output of box
will!config.py
predefines a certain set of binds which can be enabled by default
It is possible to export and import a readily installed dolmade.
./dolmades export Broken_Sword Broken_Sword.dme
./dolmades import Broken_Sword
The final goal is to be able to export the dolma on some linux system running under some hardware and import it on another linux system running another hardware. Since the user name will likely change all users home directories are shared and being symlinked to root
. Also, things can stop working if the hardware changes, e.g. sound stops working, but can be fixed easily by running winecfg
in debug mode.
Last but not least the dolma can be served on the desktop
./dolmades serve name-of-dolmade
This will create a clickable icon on the desktop and a sub-menu entry which will launch the corresponding dolmade. In addition a menu entry for uninstallation is created. It is possible to remove the menu entries and the desktop symbol again without uninstalling the dolmade:
./dolmades clearaway name-of-dolmade
You should hardly need this command but better safe than sorry!
Initialization does two things:
DOLMADES_PATH
dolmades-runtime
container with the matching version and (re)create it./dolmades init
dolmades
pulls its base images from DockerHub. The Dockerfiles specifying the build and the build script are to be found in the docker
subdirectory.
As of dolmades 1.2 all immages are for 64-bit linux only. If you need a 32-bit image you can modify the Dockerfiles and easily build them yourself. These images for releases will be tagged accordingly and not being rebuilt in future. This is what all images have in common:
$WINEPREFIX
with 32-bit prefixtargetLauncher
GUI script under /usr/local/bin
yad
required by targetLauncher
wget curl less vim
for convenienceThe following environment variables are available in a dolma (these are example values):
DOLMADES_BUILDDATE=2019-11-20
DOLMADES_GECKOVERSION=2.47
DOLMADES_WINEVERSION=4.0.2
DOLMADES_WINEBRANCH=stable
DOLMADES_VERSION=1.2
DOLMADES_UBUNTUVERSION=bionic
DOLMADES_MONOVERSION=4.7.5
LC_ALL=en_US.UTF-8
LANG=en_US.UTF-8
WINEARCH=win32
WINEPREFIX=/wineprefix
It is possible to create custom docker images on DockerHub as base for recipes which e.g. offer legacy wine, pba or Proton support.
All available tools give help output:
./dolmades help
./dolmades help bind
./cook
./box
./goglizer -h
Dolmades ships with preconfigured settings in config.py
. These are the most important ones:
VERSION = "1.2.0"
- this is the utilized version of dolmades. It derives the MAJOR_VERSION = 1.2
which serves as tag to be used for base docker images and it has to match the VERSION
setting in the Dolmafile. The syntax used in Dolmafiles is compatible across all versions sharing a common major versions.
DOLMADES_PATH = HOME + '/.dolmades-MAJOR_VERSION'
- this is the base path where dolmades stores its runtime, base images, dolmades, meta data, icons and GOG games lists. Note: you could change this path, but this will affect which host directories you can bind. A bind is never allowed to contain DOLMADES_PATH
since it would be a security issue!
A recipe is a specification which allows the guided build of the respective dolmade. Dolmafiles are for dolmades what Dockerfiles are for Docker except that dolmades are not necessarily built fully automated and hence require interaction if a graphical installer is being used.
The structure of a Dolmafile
is:
# Arbitrary comment...
COMMAND1
ARGUMENTS
FURTHER ARGUMENTS
...
COMMAND2
ARGUMENTS
...
DOLMA
Name_Of_The_Dolma
This command is mandatory. It defines the name of the dolma used internally by dolmades
. Whitespaces are not allowed.
This name is going to be slightly converted and used in the desktop icon title.
VERSION
1.2
This command is optional. It defines the tag of the base image pulled by the recipe, and has to match with the version reported by cook
. Advised to be omitted in development, such that no version checking takes place, and the latest
base image is being used.
BASE
dolmades/winehq-stable-bionic
This command is mandatory. It defines the DockerHub repository to be used. The tag of the image used is defined by VERSION
.
DESCRIPTION
A description of the contents of this dolma
This command is optional. This description is stored inside the container and it is not being used yet.
INGREDIENT
sha256
filename
description
http://remote1
ftp://remote2
file://local3
gog://remoteid
...
This command is repeatable and optional. For each ingredient used within the recipe one entry is needed.
The ingredient will be fetched from one of the locations defined and made available inside the container under filename
.
RUNUSER
cmd1 &&
cmd2 &&
... &&
cmdN
This command is repeatable and optional. This command will be launched as the calling user in a bash environment inside the dolmade. config.py:INST_PATH will be the target directory.
You can cascade multiple commands by &&
and they will be executed subsequently. The first failing command, however, will terminate the execution. If all commands succeed a final wineserver --wait
ensures the proper termination of all wine processes.
RUNROOT
cmd1 &&
cmd2 &&
... &&
cmdN
This command is repeatable and optional. This command will be launched as fake root in a bash environment inside the dolmade. config.py:INST_PATH will be the target directory.
You can cascade multiple commands by &&
and they will be executed subsequently. The first failing command however will termine the execution. Usually RUNUSER
should suffice but if you need to install some packages using apt
RUNROOT
will be required.
TARGET
targetCall
This command is optional. If omitted the dolma will launch using the target launcher and allow the user to select one of all installed targets i.e. lnk-files created during the installation. Sometimes it is desirable to launch a specific executable and then this option can be used to set the exe-binary.
TARGETARGS
targetArgs
This command is optional. Sometimes if TARGET
is used it is neccessary to also specify arguments. This can be done using this command.
TARGETENV
targetEnv
This command is optional. Sometimes it is necessary to set some environment variables for an executable. For instance it is possible to force DLL overrides or specific language settings.
TARGETPROLOGUE
targetPrologue
This command is optional. Sometimes it is necessary to call wine
using a preceding command e.g. taskset -c 0 wine
in order to limit the execution to a single CPU. This can help fix race conditions.
ICON
iconFileName
This command is optional. It specifies the icon file to be used for the desktop symbol and the target launcher with absolute path and file name.
If an absolute path is ommitted the /install
and /wineprefix/drive_c
directories will be browsed and the first occurrence of the given icon file name will be used.
If the command is omitted or the given file name cannot be found it defaults to the dolma icon.
BINDS
DirDeviceOnHost
This command is optional. It is possible to make certain locations or devices of the host system available by keywords predefined in bind.py
.
These binds are kept as setting and will be preserved when a container is being boxed, exported and imported again.
Currently predefined binds are:
FINAL NOTES
#
. Comments cannot be appended to existing command lines.INGREDIENT
- and maybe some other commands - are likely to undergo slight changes until the next releaseVERSION
of the recipe matches the dolmades
run script. Exported dolmades will contain all scripts necessary to rebuild and rerun the dolmade.Dolmades currently are a prototypical implementation done in python. Once feature-complete I want to work on an enhanced version based on Qt combining a remote repository service. The primary goal will be to create a powerful GUI to setup, maintain and run Windows software under Linux.
I figure some exciting use cases which would become addressable as well, e.g.
udocker
requires Python 2.7 and will hopefully receive Python 3 support soon: https://github.com/indigo-dc/udocker/issues/77udocker
requires tar with support of -delay-directory-restore
(see https://github.com/indigo-dc/udocker/pull/137) which every recent distro should providedolmades
will be written to support Python 2.7 and bearing in mind Python 3 compatibility for later when udocker starts supporting it, too.winetricks
has been used in the recipeudocker
fails to pull some layers from the docker registry (timeouts) - simply repeating the commands should help.Last but not least: if you are in trouble, check out the issues and open a new one if applicable.