Skip to content

Commit

Permalink
improved wine helpers and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Jelmerro
Jelmerro committed Dec 21, 2018
1 parent 299d01f commit 30b5c86
Show file tree
Hide file tree
Showing 2 changed files with 90 additions and 35 deletions.
87 changes: 66 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,9 @@ There is one trade-off to all these advantages:

- A regression in a new version of wine can break compatibility until a new wine version is released

The [wine wiki](https://wiki.winehq.org/FAQ#Which_version_of_Wine_should_I_use.3F) recommends to use a recent or even the latest version of wine,
which is automatically configured by using carafe.

### Manage carafe

After running `./carafe` a list of the supported options will shown.
Expand All @@ -107,7 +110,7 @@ All of them are listed in the output as shown here:
```
usage: carafe {<carafe_name>,list} <sub_command>
Welcome to carafe 0.3.0-beta
Welcome to carafe 0.3.0
carafe is a tiny management tool for wine bottles/carafes.
optional arguments:
Expand All @@ -116,14 +119,15 @@ optional arguments:
sub-commands:
All the valid sub-commands to manage the carafes
{create,install,start,remove,info,link,shortcut,winecfg,winetricks}
{create,install,start,remove,info,link,shortcut,regedit,winecfg,winetricks}
create create a new carafe
install install software to the carafe
start start an installed program
remove remove a carafe
info all info about a carafe
link link a program to the carafe
shortcut generate a desktop shortcut
regedit run regedit
winecfg run winecfg
winetricks run winetricks
Expand Down Expand Up @@ -380,34 +384,63 @@ optional arguments:
Executable location will be asked interactively when not provided as an argument,
in a fairly similar way as is done for the 'link' command.

Shortcuts won't be automatically deleted when a carafe is deleted.

Some programs might create a desktop shortcut during the installation,
these type of shortcuts are made by wine and don't need carafe to work.

#### Winecfg and Winetricks
Shortcuts won't be automatically deleted when a carafe is deleted.

#### Regedit

Example usage of regedit for a Steam carafe looks like this:

`./carafe steam regedit`

Both of these commands accept no arguments besides `--help`.
To open the regedit for a Steam carafe without using carafe, the following command could be used:

`WINEPREFIX=/home/user/.carafe/steam wine regedit`

This is exactly what carafe will do when asked to invoke regedit,
but carafe makes sure the winearch and wineprefix are automatically correct.

#### Winecfg

Example usage of winecfg for a Steam carafe looks like this:

`./carafe steam winecfg`

They will directly execute the winecfg or winetricks command respectively.
In the last paragraph, it's explained how these commands are handled,
and how you can run them directly without using the carafe interface.
Running winecfg without carafe works the same as for regedit.

#### Winetricks

Example usage of winetricks for a Steam carafe looks like this:

`./carafe steam winetricks`

The carafes are created by running prefixed wine commands.
All features available using wine, winecfg, winetricks or any other tool can be used with carafe.
This will open the winetricks GUI, where a lot of extra components can be installed from.
To install dxvk for the steam carafe with winetricks, run the command:

For example, to open the winecfg for a Steam carafe, the following command could be used:
`./carafe steam winetricks dxvk`

`WINEPREFIX=~/.carafe/steam winecfg`
The help page describes this behavior as follows:

This is exactly what carafe will do when asked to invoke winecfg,
but carafe makes sure the arch and wineprefix are automatically correct.
```
usage: carafe <carafe_name> winetricks <optional_arguments>
Use 'winetricks' to install winetricks components
positional arguments:
arguments Any arguments will directly be passed to winetricks
optional arguments:
-h, --help show this help message and exit
```

The same shortcut is added for winetricks, other tools can use the original wineprefix command.
Just like winecfg and regedit, it's also possible to run winetricks commands without carafe:

`WINEPREFIX=/home/user/.carafe/steam winetricks dxvk`

This again means that you need to manually set the wineprefix and winearch to the correct values,
which is something that the carafe command will handle for you.

In short, carafe is aimed to ease the configuration of wine bottles/carafes,
without introducing any magic or changing the wine prefix system.
Expand All @@ -419,21 +452,33 @@ carafe is pure python and only uses native imports, some of them are python 3.5+
Wine is the only dependency of carafe and it can even do some management tasks without wine installed (such as remove, info and list).
Creating and starting the carafes is done by wine, and won't work without it installed.

By default carafe will look for the commands: wine, wineboot and winecfg.
All of these should automatically be set when installing wine using the package manager.
carafe will show a warning when wine or the other commands are not found,
carafe will show a warning when the 'wine' command is not found,
and offer instructions to resolve the problem.
For other installation methods an alias might be needed,
For some installation methods an alias might be needed,
or you can configure the wine location in the config file.
You can manually edit the `~/.carafe/config.json` to change the default wine command locations.
You can manually edit the `~/.carafe/config.json` to change the default wine command location.
It might be needed to create the config file, as it normally will only be stored when links or special arch types are used.
The config file also accepts a 'winetricks' field for setting the winetricks location/path separately.

### Logging

No wine commands executed by carafe will show any output in the terminal.
The commands will store the log of the latest executed command as `~/.carafe/<carafe_name>/log`.
carafe does not keep a history of all the logs, only the latest one is stored.

### Wine related files

Wine will create menu shortcuts in `~/.local/share/applications`,
and store the icons for them in `~/.local/share/icons`.
The location `~/.local/share/desktop-directories` will also be used,
along with `~/.config/menus` for menu related files.

These directories are automatically filled with files by wine,
carafe does not create, modify or remove them.

carafe stores all configuration and the prefixes in `~/.carafe`,
which will automatically be deleted when all carafes are removed.

## License

carafe itself is made by [Jelmer van Arnhem](https://github.com/jelmerro) and is licensed as MIT, see LICENSE for details.
Expand Down
38 changes: 24 additions & 14 deletions carafe
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ __author__ = "Jelmer van Arnhem"
# See README.md for more details and usage instructions
__license__ = "MIT"
# See LICENSE for more details and exact terms
__version__ = "0.3.0-beta"
__version__ = "0.3.0"
# See https://github.com/jelmerro/carafe for repo and updates

import argparse
Expand Down Expand Up @@ -104,8 +104,6 @@ def check_for_tool(name, location):
# It's recommended to change them manually in the config file and not here
conf = read_config()
WINE = conf.get("wine", "wine")
WINEBOOT = conf.get("wineboot", "wineboot")
WINECFG = conf.get("winecfg", "winecfg")
WINETRICKS = conf.get("winetricks", "winetricks")
check_for_tool("wine", WINE)

Expand All @@ -115,8 +113,7 @@ class Carafe:

def __init__(self, name):
self.name = name
self.forbidden_names = [
"config.json", "wine", "wineboot", "winecfg", "winetricks"]
self.forbidden_names = ["config.json", "wine", "winetricks"]
if not self.name:
print("The current name is not allowed because it appears empty")
sys.exit(1)
Expand All @@ -140,8 +137,7 @@ class Carafe:
remove_config(self.name)
if self.arch:
modify_config(self.name, "arch", self.arch)
check_for_tool("wineboot", WINEBOOT)
self.run_command(f"{WINEBOOT} --init")
self.run_command(f"{WINE} wineboot --init")

def install(self, args):
self.exists()
Expand Down Expand Up @@ -248,15 +244,21 @@ class Carafe:
with open(output_file, "w") as f:
f.write(shortcut_contents)

def regedit(self, args):
self.exists()
self.run_command(f"{WINE} regedit")

def winecfg(self, args):
self.exists()
check_for_tool("winecfg", WINECFG)
self.run_command(f"{WINECFG}")
self.run_command(f"{WINE} winecfg")

def winetricks(self, args):
self.exists()
check_for_tool("winetricks", WINETRICKS)
self.run_command(f"{WINETRICKS} --isolate")
arg_string = " "
for arg in args.arguments:
arg_string += f"{arg} "
self.run_command(f"{WINETRICKS} {arg_string}")

# Class helper functions

Expand Down Expand Up @@ -418,12 +420,12 @@ if __name__ == "__main__":
"-l", "--location",
help="Location of the executable inside the carafe to start")
# Remove
sub_remove = sub.add_parser(
sub.add_parser(
"remove", help="remove a carafe",
usage="carafe <carafe_name> remove",
description="Use 'remove' to delete an existing carafe")
# Info
sub_info = sub.add_parser(
sub.add_parser(
"info", help="all info about a carafe",
usage="carafe <carafe_name> info",
description="Use 'info' to print all information about a carafe")
Expand Down Expand Up @@ -452,16 +454,24 @@ if __name__ == "__main__":
sub_shortcut.add_argument(
"-t", "--type", choices=["carafe", "wine"],
help="The type of shortcut to make")
# Regedit
sub.add_parser(
"regedit", help="run regedit",
usage="carafe <carafe_name> regedit",
description="Use 'regedit' to edit the windows registry")
# Winecfg
sub_cfg = sub.add_parser(
sub.add_parser(
"winecfg", help="run winecfg",
usage="carafe <carafe_name> winecfg",
description="Use 'winecfg' to configure all wine settings")
# Winetricks
sub_tricks = sub.add_parser(
"winetricks", help="run winetricks",
usage="carafe <carafe_name> winetricks",
usage="carafe <carafe_name> winetricks <optional_arguments>",
description="Use 'winetricks' to install winetricks components")
sub_tricks.add_argument(
"arguments", nargs=argparse.REMAINDER,
help="Any arguments will directly be passed to winetricks")
# Actually handle all the arguments
args = sys.argv[1:]
if not args:
Expand Down

0 comments on commit 30b5c86

Please sign in to comment.