Instructions For Making Eets Munchies Integrate Cleanly Into A Linux Desktop

[ssokolow]

For users, skip to my second post in this thread. For developers, continue reading.

 

While trying to get Eets Munchies added to my launcher menu, I got the impression that you guys don't have much experience with this sort of thing, so here's a quick primer on how to make a game a proper citizen on a Linux desktop:

 

First, your "eets2" launcher script has three bugs. Change it to this:

#!/bin/shcd "`dirname \"$0\"`"exec ./updater/6/updater

Bug 1: Omitting the shabang line at the top doesn't mean it's not a shell script, it just means it'll run in whatever shell the user prefers... even if the syntax isn't compatible.

 

The POSIX standard requires that the OS provide a Bourne-compatible shell at /bin/sh so my advice is to start all your scripts with #!/bin/sh and make sure your script runs fine on dash (dash is what /bin/sh points to on Ubuntu-family distros and is the most minimal Bourne shell I've found used in that role on a desktop Linux so, if it works on dash, it should work on anything.)

 

If you want to be thorough, also test that the game launches properly with "bash eets2" (bash is what Ubuntu used to point /bin/sh at and it's what pretty much every other Desktop Linux still does) and "busybox sh eets2" (BusyBox is an ultra compact "all your core tools in one program" offering primarily seen on embedded systems but it's conceivable that some quirky user might have it as their /bin/sh and it's theoretically possible it might be slightly more minimal than dash).

 

Bug 2: On Linux, you can't assume that the current directory will be the same one your script is in.

 

Unless you actually cd elsewhere (eg. in a terminal), applications are run in $HOME as an easy way for globally-installed applications to know where to look for the user's documents.

 

If you want eets2 to work when double-clicked or run by typing the absolute path in a  Run... dialog, you need to use that cd construct. (It takes advantage of the fact that a script's argv[0] equivalent will be a path relative to the current working directory)

 

Bug 3: Since your script is just going to exit immediately when Eets 2 closes, call the updater using exec

 

I'm guessing you assumed that, when eets2 called the updater, it would exit, similar to how it works with one .BAT file calling another .BAT file without using CALL on Windows.

 

That's not the case. Like a compiled C or C++ program, shell scripts stick around until they hit exec, exit, or the end of the file.

 

Since the script isn't going to do anything but exit when the updater (and the copy of Eets 2 it launches) does, it's bad form to leave a shell interpreter cluttering up memory and the task manager.

 

Once you've fixed those bugs, adjusting your first-run wizard to add a launcher menu icon and/or a desktop icon is trivial.

 

First, provide a copy of eets2.xpm in PNG or SVG format for the recommended best mix of compatibility and utility. Name it something like kleientertainment-eets2.png (The system requires a vendor prefix to simplify telling the difference between an update and a naming collision.)

 

On a system with ImageMagick installed (very common), you can just run this:

convert eets2.xpm kleientertainment-eets2.png

Then, write a desktop entry definition and save it as kleientertainment-eets2.desktop (again, vendor prefix for namespacing purposes).

[Desktop Entry]Encoding=UTF-8Name=Eets MunchiesType=ApplicationExec="PATH_TO_CURRENT_DIR/eets2"TryExec=PATH_TO_CURRENT_DIR/eets2Icon=kleientertainment-eets2Categories=Game;PuzzleGame;

This is why you needed to adjust your launch script. While you could theoretically use Path=PATH_TO_CURRENT_DIR, I've found support for it in desktop launchers to be spotty and doing so won't fix the case where the user types out the path in the run dialog.

 

The TryExec line tells it to hide the launcher entry if the referenced file isn't present and executable so users can't get orphaned launcher entries if they simply delete the eets2 folder. The Categories line is what powers the automatic categorization in Linux launcher menus.

 

You can read more about the format in the compact and very understandable XDG Desktop Entry specification. (As it says in the spec, the list of allowed categories is in appendix A of the related XDG Desktop Menu specification.)

 

Once you've got your icon and launcher, adding them is as simple as two or three commands (depending on what users want):

# Add the icon to the system's fallback theme so the launcher can find itxdg-icon-resource install --size 256 kleientertainment-eets2.png# Add Eets Munchies to the user's launcher menu and anything using the same data# (For example, launchers inspired by Quicksilver, such as GNOME Do)xdg-desktop-menu install kleientertainment-eets2.desktop# Add a desktop icon for Eets Munchiesxdg-desktop-icon install kleientertainment-eets2.desktop

That's it. That .desktop file would also be where you specified the associated file types if you were writing something like a text editor or media player. (I'm told OSX does something similar using plist files)

 

As for easily generating the .desktop file with hard-coded paths on first run, it'd probably just be simplest to call the shell script snippet I'm giving in the following post and let the shell's variable substitution act as a simple templating system. It's not perfect (It doesn't escape double-quotes in the Exec path) but it should work 99% of the time. simplex replied with a version that does escaping a couple of posts further down.

[ssokolow]

Users, here's how to add a launcher menu and/or desktop icon for Eets Munchies to your Linux system without waiting for the devs.

 

Simply open a terminal in your eets2 folder (either use cd or, if your file manager offers it, the "open terminal here" menu entry) and do the following:

1. Type convert and press Enter. If it says the command wasn't found, use your package manager to install ImageMagick.
2. Type xdg-desktop-menu and press Enter. If it says the command wasn't found, you'll want to install xdg-utils for a lot of reasons beyond needing it here. (And you're probably using a distro that assumes you've got a bit of highly-experienced control freak in you.)
3. Copy-paste or type the following into your terminal (You can skip the # lines):

# NOTE: Thanks to simplex for catching a bug in my generation of run_eets2.sh# Prepare the icon and install it into your desktop's fallback themeconvert eets2.xpm kleientertainment-eets2.pngxdg-icon-resource install --size 256 kleientertainment-eets2.png# The updater undoes any changes to the eets2 script, so we need to give it its own# wrapper to make sure the current directory is correctcat << EOF > run_eets2.sh#!/bin/shcd "\`dirname \"\$0\"\`"exec ./eets2EOF# Mark it executablechmod +x run_eets2.sh# Create a launcher definition for the game with the correct pathscat << EOF > kleientertainment-eets2.desktop[Desktop Entry]Encoding=UTF-8Name=Eets MunchiesType=ApplicationExec="$PWD/run_eets2.sh"TryExec=$PWD/eets2Icon=kleientertainment-eets2Categories=Game;PuzzleGame;EOF# Install the launcher into the menuxdg-desktop-menu install kleientertainment-eets2.desktop# Add a desktop iconxdg-desktop-icon install kleientertainment-eets2.desktop

You may need to press enter after pasting if you didn't include that last newline when copying.

 

UPDATE: simplex has updated this script to escape the Exec line so that even double-quotes can be used in folder names for the path to eets2. (It's just a couple of posts below this one.)

[Eets]

Interesting! I have my laptop running linux and might give this a try!

[simplex]

Very nice! Perfect FreeDesktop compliance. ;]

Just because you mentioned the highly unlikely corner case where the Exec path would require escaping, I decided to tweak the script to account for that.

I also took the opportunity to change run_eets2.sh's generation so the backtick expansion will happen at run-time, and not when it's generated, in particular relieving the need to escape the path there as well.

#!/bin/sh# Prepare the icon and install it into your desktop's fallback themeconvert eets2.xpm kleientertainment-eets2.pngxdg-icon-resource install --size 256 kleientertainment-eets2.png# The updater undoes any changes to the eets2 script, so we need to give it its own# wrapper to make sure the current directory is correct## Tweaked to do the backtick expansion at run time, and not on generation time.cat << EOF > run_eets2.sh#!/bin/shcd "\`dirname \"\$0\"\`"exec ./eets2EOF# Mark it executablechmod +x run_eets2.sh# Escapes reserved characters for the Exec path.EXEC_PATH=`echo "$PWD/run_eets2.sh" | sed 's/\(["\`$\\]\)/\\\1/g'`# Create a launcher definition for the game with the correct pathscat << EOF > kleientertainment-eets2.desktop[Desktop Entry]Encoding=UTF-8Name=Eets MunchiesType=ApplicationExec="$EXEC_PATH"TryExec=$PWD/eets2Icon=kleientertainment-eets2Categories=Game;PuzzleGame;EOF# Install the launcher into the menuxdg-desktop-menu install kleientertainment-eets2.desktop# Add a desktop iconxdg-desktop-icon install kleientertainment-eets2.desktop

[GreenWyvern]

Someone give this guy a cake!

[ssokolow]

I also took the opportunity to change run_eets2.sh's generation so the backtick expansion will happen at run-time, and not when it's generated, in particular relieving the need to escape the path there as well.

 

Ahh, yes. Thanks.

 

It was getting late when I wrote the "for users" version and so I got sloppy and just tested that the things I added later were working without actually looking into the generated files.

 

I've copied that fix into my version and added an acknowledgement for you. I'm not yet sure whether I want to copy your enhancement for quoting Exec since doing so would complicate the narrative of this thread.

 

Edit: I decided to just mention your improved version from my posts.

[simplex]

Ahh, yes. Thanks.

 

It was getting late when I wrote the "for users" version and so I got sloppy and just tested that the things I added later were working without actually looking into the generated files.

 

I've copied that fix into my version and added an acknowledgement for you. I'm not yet sure whether I want to copy your enhancement for quoting Exec since doing so would complicate the narrative of this thread.

 

Edit: I decided to just mention your improved version from my posts.

No problem. I just wrote the quoting stuff because you explicitly mentioned it as a minor setback. I wouldn't generally have bothered with it, and it does hurt readability.

[Wade]

Okay, I'll pass the information onto the programmers so they can take a look at it.

 

Thanks!