Menu entries - How to write a Puppy .desktop file...

[mikewalsh]

Afternoon, gang.

Following a suggestion from bigpup - about turning some of the content of a post I made earlier today into a 'How-to' explainer - I decided it would be a good idea.

The subject is that perennial old chestnut; how to write a .desktop file that will generate a working Menu Entry in Puppy.....and how do you achieve it? I've been writing these things for years, and can almost do them in my sleep now, I've created so many of them.

I thought it might be nice to share that knowledge, in a clearly-written 'tutorial'. Very briefly:-

• The files that generate Menu entries are called xxxxxxxxx.desktop files (where "xxxxx" will be the name of the application or program.)

• The name is usually (though NOT always) the name of the app/program itself. (You CAN call it whatever you want, but short and to-the-point is usually best).

---------------------------------------------------------------

A bit of background:-

The folks at FreeDesktop.org are the people in charge of maintaining cross-platform, cross-architecture specifications & standards. I'm sure most of us have looked at .desktop files from time to time; some of them, containing tons of localization stuff, designed to cater for all languages globally, can run into hundreds of lines.

Most of the big 'projects', when they release software, have to try and ensure their .desktop entries will be compatible with every possible combination of display server/window manager/filesystem manager/ desktop environment (DEs) you can imagine. Some of these use lines & categories that are specific to them, and them alone......but it all still has to be included.

Fortunately, we're not so constrained here in Puppyland. Much of this stuff can be 'junked'; all that Puppy requires to give a fully functional Menu entry boils down to a handful of lines.....which I will now demonstrate. This is just an example:-

Code: Select all

[Desktop Entry]
Encoding=UTF-8
Name=Audacity
Comment=Edit/record audio files...
Exec=audacity
Icon=audacity
Type=Application
Terminal=false
Categories=X-Multimedia

A quick explanation of each line:-

[Desktop Entry] - this is the bog-standard, default first-line entry for every .desktop file I've ever seen, as provided for in the freedesktop.org standards. This defines it as being a Menu entry configuration file.

-------

Encoding=UTF-8 - this is the recommended character setting for defining ASCII characters. I never mess with this one.

-------

Name - this will be the name of the entry as it appears in your Menu.

-------

Comment - optional, but if you provide this, you get a wee tooltip showing the exact same text when browsing through the various .desktop files in /usr/share/applications.

-------

Exec - the command/name of the executable that will launch your application. A properly-constructed standard .pet or .deb package - or an SFS - will place this command in one of a handful of standard locations (usually the 'bins'; /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin.....and a Puppy 'special', /root/my-applications/bin). These are always defined as being "in the $PATH"; I forget the specific file, but there is one in every Puppy, usually loaded at boot-time, that defines these '$PATHs' to the system.

When your executable lives 'in the $PATH', only its name is needed here. Nothing else. Puppy WILL find it.

(If your executable lives in a non-standard location - and there is no fixed requirement that it MUST be in a standard one; things will run from anywhere in a Linux system - simply provide the $PATH in full. We just want the Menu entry to find it when requested to do so.)

-------

Icon - self-explanatory. The small image that sits in front of the Menu entry, and also displays with your .desktop file in /usr/share/applications. These often live in /usr/share/icons in the "big boys", under tons of sub-directories that specifically define them to particular parts of a mainstream distro. In Puppy, we use, usually, one of two locations; either /usr/share/pixmaps, or sometimes /usr/local/lib/X11/pixmaps.

(You can obtain icons for pretty much anything with a web-search for, say, "PNG icons for xxxxxxx (whatever)". I recommend PNG icons because of the transparency layer; these blend-in far better to any background you place them on. Size isn't too important; anywhere from 128x128 up to and including 512x512 will work. Larger icons give sharper detail when re-sized down to 48x48; ROX-filer will automatically do this where necessary.)

If you're really adventurous, and fairly competent with a vector or raster graphics editor, you could always make your own. I've done this on several occasions over the years.
-------

Type - this, according to FreeDesktop.org, can be one of three things. 'Application' (almost always), 'link' or 'directory'. I've never seen either 2 or 3 used. Ever.

-------

Terminal - defines whether or not the application runs in a terminal. Options are 'true' or 'false' - usually the latter - and this is the only one that is always written in small letters, for some reason.

-------

Categories - defines which area of the Menu your application will occupy when 'installed'. Usually, it's sufficient - to get a 'working' entry - to simply stick "X-" in front of the required Menu category. E.g., "X-Desktop", "X-Utility", "X-System", etc. If you want to be more specific, find another app in the same place in the Menu, look up its .desktop file in /usr/share/applications, then open that up with Geany & 'borrow' the Categories line. It usually works.

-------

Occasionally, an optional extra line - MimeType - is included. This is not compulsory, but can be used to associate a particular application with specific 'mime-type' files, as provided in /root/Choices/MIME-types.

These should be listed, and separated by semi-colons ";". Don't leave spaces between them.

-------

If you write these from scratch, go into /usr/share/applications, rt-clk in an empty bit of the window->New->Blank file. It's NOT a script; rather, it's a set of instructions that tell the rest of the system where to look for stuff, and then what to actually DO with it. Don't forget to append the .desktop suffix when you name it. You'll need to rt-clk it fairly quickly when the file is blank and you're ready to write the lines out; hovering over the .desktop entry, the system attempts to 'parse' it.....and if it's blank, it moans that it can't read it & throws up an error message.

If you get the error message, just clear it and try again.....right-click a little bit quicker next time!

-------

And that, mes amigos, is how to write a basic, functional Menu entry for Puppy Linux. After you've created your .desktop file, and placed a suitable icon in the desired location, all you need to do is to open a terminal, run

Code: Select all

fixmenus

.....and wait for it to come back to the prompt "#" (doesn't take many seconds), then re-start JWM:-

Code: Select all

jwm -restart

Less disruptive than re-starting the graphical server - which closes anything you may have open, and can lose work in the process - re-starting JWM will still place the Menu entry where we want it. After all this time, I've long had one-click scripts that do all this stuff for me.

Your Menu Entry should now be showing in the desired location, and should be fully functional.

Hope some of you guys find this helpful.

Mike.

[wizard]

Nice job Mike, thanks for the details. I've had to fool with .desktop files in the past that either didn't work or just didn't exist.

wizard

[mikewalsh]

Nice job Mike, thanks for the details. I've had to fool with .desktop files in the past that either didn't work or just didn't exist.

wizard

You're very welcome, wizard. I can't remember ever seeing a specific tutorial on this matter, and after bigpup suggested it, I thought "Why not..?"

Hope it helps.

Mike.

[tosim]

Thanks a lot for that quick, useful tutorial.

[mikewalsh]

Thanks a lot for that quick, useful tutorial.

You're welcome, tosim. Hope it's useful, and takes some of the "mystery" out of it. It's pretty straight-forward, once you've done 'em a few times.

Mike.

[bigpup]

Yes this is very much needed and very helpfull to all.
Thanks for doing this!!

Just to help really, really new people to Puppy.

I suggest you provide a statement, in the very beginning, of something like this.

Menu entries are provided by a file in /usr/share/applications/
The file is a .desktop file.
The name of the file is usually the name of the program.
Example:
For Firefox browser.
firefox.desktop

I know you kind of say this latter in the info.
But think like someone that knows nothing about this.
Too much info is never a problem.

For the icon= entry
Sometimes you have to provide the exact location info for the icon.
Example:
Getnvidia
Icon=/usr/share/icons/hicolor/48x48/apps/getnvidia.png

[peebee]

For info:

Type - this, according to FreeDesktop.org, can be one of three things. 'Application' (almost always), 'link' or 'directory'. I've never seen either 2 or 3 used. Ever.

'link' doesn't work in RoxFiler / JWM but it does work in other desktops (e.g. PcManFM / LXDE) - Exec= is replaced by URL= and the desktop file then opens a web address....

e.g.
[Desktop Entry]
Type=Link
Encoding=UTF-8
Name=Puppy Linux Forum
URL=https://forum.puppylinux.com/
Icon=/usr/share/pixmaps/puppy/puppy.svg

[mikewalsh]

@peebee :-

Thanks for the info, Pete. That's the first time I've ever seen that used, y'know..!

(Of course, there's easy workarounds for doing what you've demonstrated in JWM. Slightly more long-winded, perhaps, but still simple enough to achieve.)

Mike.

[bigpup]

Used the info in this topic, to make a menu entry, for updating the save, when running in pupmode 13.

Never seen this in the menu, so wanted to see if a menu entry, could work the same as the save icon, on the desktop.

I now have save update menu entry.

[davids45]

G'day Mike,

Perhaps some examples of complete .desktops for different catagories? Ones for tricky situations that Puppians have encountered (and solved)?

And I've had many a whine about wine menus. So an example or two for common wine apps.

David S.

[mikewalsh]

@bigpup :-

In theory, anything that'll run from a desktop icon can also run from a Menu entry. If you're 'clicking' on a desktop icon to launch something, then there's an executable action there. That action can be translated to a .desktop file, and from there into a Menu Entry.

In general, any item that stays in one fixed location (say, /usr/bin or /usr/local/bin), and keeps the same name all the time, I will write the executable action directly into the Exec line of the .desktop file. If, however, I have items that may occasionally get moved - or altered in some way - I will create a small launch script in /root/my-applications/bin. This will perform the actual app launch, then the Exec line of the .desktop file will point to this instead....

This adds a degree of flexibility, and does away with the need to run 'fixmenus' & re-start JWM every time you change anything.....because the .desktop entry doesn't change at all. It's the launcher that gets edited, and HERE the change is immediate.

-----------------------------------

@davids45 :-

G'day Mike,

Perhaps some examples of complete .desktops for different catagories? Ones for tricky situations that Puppians have encountered (and solved)?

And I've had many a whine about wine menus. So an example or two for common wine apps.

David S.

Good idea, David. The 'categories' thing is more complex than it looks; I've never found a comprehensive guide to the sub-categories within each category. I think I once spotted such a list on the wiki, but I've never been able to find it again.....I suspect the wiki has been edited at some point, and links may have been lost.

I usually just take a look at one that sits in the same location as what I want to use, then 'borrow' the Category. 99 times out of 100, it works....

I'll post some examples soon, including for WINE Windoze apps/progs.

Mike.

[bigpup]

For the different programs that are part of Wine.
This pet installs menu entries for them.
https://archive.org/download/Puppy_Linu ... s-v2.1.pet
It is basically a bunch of different .desktop files, for each program, that are part of Wine.

Now, a menu entry, for a specific Windows based program, that you install.
That is going to be a make your own .desktop file.

[Mr Crunchbang]

I was just searching for this on the search button and boom Mike comes through with the goodies

Thanks for the useful guide Mike

[DougSmithshop]

For info:

Type - this, according to FreeDesktop.org, can be one of three things. 'Application' (almost always), 'link' or 'directory'. I've never seen either 2 or 3 used. Ever.

'link' doesn't work in RoxFiler / JWM but it does work in other desktops (e.g. PcManFM / LXDE) - Exec= is replaced by URL= and the desktop file then opens a web address....

e.g.
[Desktop Entry]
Type=Link
Encoding=UTF-8
Name=Puppy Linux Forum
URL=https://forum.puppylinux.com/
Icon=/usr/share/pixmaps/puppy/puppy.svg

i did this, and on the latest Fossapup I get the error:
"Can't find Exec command in .desktop file '/root/my-applications/bin/PupForum'"
Here is my .desktop file:

[Desktop Entry]
Type=Link
Encoding=UTF-8
Name=Puppy Linux Forum
URL=https://forum.puppylinux.com/
Icon=/usr/share/pixmaps/puppy/puppy.svg

I am less than a week into Linux, and I have no idea what that error message means, or how to fix it, as I do not see any "Exec" files or anything similar. The URL is correct, working when I click on it. Please explain this to me.

[Feek]

Hello and welcome,
out of curiosity I tried this desktop entry with the "url" line instead of "Exec" line and got the same error message as you.
My next attempt was this:

Code: Select all

[Desktop Entry]
Type=Link
Encoding=UTF-8
Name=Puppy Linux Forum
Exec=defaultbrowser https://forum.puppylinux.com/
Icon=/usr/share/pixmaps/puppy/puppy.svg

And it seems to work. After clicking on this .desktop file my default browser will open the desired url.
I'm using VanillaDpup64 now.

[williams2]

Please explain this to me.

If you click on a .desktop file in a Roxfile window, rox is the handler for the file.
Apparently, rox requires the Exec line
and rox doesn't work with the URL syntax.

I'm not sure exactly what you are trying to do.

If you replace this:

Code: Select all

URL=https://forum.puppylinux.com/

with this:

Code: Select all

Exec=xdg-open https://forum.puppylinux.com/

then it will probably do what you want.
But it is a sort of a workaround.

The explanation is that rox is being used to handle xdg uri's
and rox has limited compatibility with xdg,
which is why .desktop files don't always work properly,
although sometimes a .desktop file can be tweaked to work with rox.

[je55eah]

Thanks for sharing this.

You'll need to rt-clk it fairly quickly when the file is blank and you're ready to write the lines out; hovering over the .desktop entry, the system attempts to 'parse' it.....and if it's blank, it moans that it can't read it & throws up an error message.

If you get the error message, just clear it and try again.....right-click a little bit quicker next time!

Perhaps the file could be named application.desktop.txt, then edited, then renamed to application.desktop.

If, however, I have items that may occasionally get moved - or altered in some way - I will create a small launch script in /root/my-applications/bin. This will perform the actual app launch, then the Exec line of the .desktop file will point to this instead....

That makes sense. I see that /usr/bin/ also contains scripts like this. Is there a reason to place them in /root/my-application/bin/? It seems like it would be better if they all resided in one location.

As an example seamonkey-spot launches seamonkey as spot. That is a topic I would like more clarification about.

If I were to install a webbrowser such as firefox, then I have seen an example where it is launched by running:

Code: Select all

apulse run-as-spot  /appdirhere/firefox

The apulse seems to be unnecessary. Run as spot makes sense, but I haven't inspected that script. The strange thing is that when I look at seamonkey-spot it does some other stuff such as:

Code: Select all

if [ "$PROGRAM" = program ]; then
	die 0 "Symlink whatever-spot to me, to launch \"whatever\" as spot." 
fi

! [ $(id -u) = 0 ] && exec $PROGRAM "$@"
SPOT_HOME=$(awk -F: '$1=="spot" {print $6}' /etc/passwd)

before it expectedly calls:

Code: Select all

exec /usr/bin/run-as-spot $PROGRAM "$@"

Is that other stuff superfluous?

I also have a question about pburn and some of the rox apps.
What is the point of the rox app for pburn which calls

Code: Select all

"/usr/local/pburn/pburn" "$@"

when there is also a pburn.desktop which includes:

Code: Select all

Exec=pburn

Speaking of rox apps; they are essentially doing the same thing as the scripts you place in /root/my-application/bin/, but rather than being an executable script, they are an executable directory containing an AppRun script. How does one create a .desktop file which executes a RoxApp directory?

I placed a firefoxESR install into a RoxApp folder and created a desktop entry which includes:

Code: Select all

Exec=run-as-spot /usr/local/apps/firefox/firefox  %U

It seems like there whole RoxApp part is unnecessary. If I didn't install firefoxESR into /usr/local/apps/firefoxESR/ should I have placed it into /usr/local/firefoxESR/ like pburn, or is there yet another location where people are supposed to put things?

I see a lot of redundancy and chaos in the UNIX filesystem.

[williams2]

A Rox Application Directory is a directory that contains an executable file named AppRun in the directory.

If a RoxApp dir is clicked in a RoxFiler window, Rox will execute the AppRun file.
as opposed to showing you the files that are in the dir,
which is what rox would normally do.

To run a RoxApp from the command line or from a shell script you can execute the AppRin file like this:

Code: Select all

/usr/local/apps/Geany/AppRun

Or you can use RoxFiler to execute the RoxApp dir, like this:

Code: Select all

rox /usr/local/apps/Geany/

Running Rox with a file name as a parameter
does the same thing as clicking that file in a RoxFiler window.
Rox runs the app as a background process.

[mikewalsh]

@je55eah :-

This IS getting rather 'off-topic' for this thread's subject matter, but.....here goes.

You'll find a lot of what appears to be "multiple redundancy" in Linux in general.....and in Puppy in particular. With Puppy's "running-as-root" model, and its rather unique way of approaching many of the traditional Linux ways of doing things, you'll often discover what appear to be several different methods for accomplishing the same tasks.

One of the nice things about Linux is its extreme flexibility. Yes, on a system level, there ARE standard, accepted locations for certain binaries, dependencies and config files. Many of these are dictated by whatever display server you're running.....which in Puppy is more often than not the "X" display server. This uses a whole heap of pretty much 'standard' dependencies & other items, regardless of what Puppy you happen to be using, so it's not a good idea to mess with this stuff in any way, shape or form.

(Some Puppy devs are now working on ways to easily implement the fast-becoming 'standard' Wayland display server, but it's still rather early days for this as yet).

However, when it comes to app-specific stuff, there are no hard and fast rules. Most mainstream distros tend to use standard locations for everything, because it's just easier.....it permits straight-forward usage of software that tends to be written to use standard file-system locations. Indeed, many Linux veterans often get extremely snotty with those who don't want to do things the "traditional" way; often citing all kinds of things that the user in question can then expect to go drastically wrong! But it doesn't have to be so; app-specifc executables, dependencies and configuration files CAN be placed pretty much anywhere IF YOU WANT TO DO SO. It may entail giving the 'full' $PATH to each item, because of using non-standard locations, but so long as an app can find everything it requires to run, there is no reason why it shouldn't.

Things like .desktop entries are best placed in the correct locations, because it makes them far easier to then give a 'standard' template to work from, as I've done here.

-----------------------------------

The ROX-app is something of a Puppy-special. Despite that ROX-filer is by no means exclusive to Puppy - it's offered as an alternative on many other lightweight distros - from what I've been able to ascertain over the years, we're the only ones who seem to use ROX-apps on a semi-regular basis. It lends itself perfectly to the creation of totally 'portable' applications; in fact, the way I've built the range of 'portable' apps I've created for the community, any one of these can be turned into a single-click-to-launch 'executable' directory by the simple expedient of creating a sym-link to the 'LAUNCH' script.....named AppRun. These will then all behave AS ROX-apps.

--------------------------------

With regard to that Firefox 'launcher' you've quoted above, the 'apulse' at the start of the exec line is NOT superfluous at all, because without it you will get no audio out of Firefox.

From the mid-v50s, the Mozilla dev team re-wrote Firefox to expect to use the now largely-standard PulseAudio. Puppy doesn't use PulseAudio; OOTB, it uses the standard ALSA (which underlies PulseAudio anyway, but.....I digress). PulseAudio is an intermediate 'control' layer between ALSA and the application, which is supposed to give much finer-grained control of your audio components, but for us it's often proven to be problematic to implement. Some Puppians have re-mastered Puppies to use PulseAudio, but the easier workaround is to employ the 'apulse' library instead.

All 'apulse' does is to provide a way to translate the PulseAudio commands directly into ones which ALSA can immediately understand.....while at the same time, permitting apps that 'expect' PulseAudio to 'see' it and be happy! It's simpler, easier to implement, is far smaller & leaner, and.....it just 'works'.

Mike.

[je55eah]

Thank you @williams2 and @mikewalsh .

Code: Select all

the 'apulse' at the start of the exec line is NOT superfluous at all, because without it you will get no audio out of Firefox.

I saw that this problem is occurring in another thread, but I wrote my question before reading that because I did test firefox without apulse and the audio was working.

Aren't these apps already portable in the sense that they can be placed wherever and executed by running firefox or pburn instead of Rox and the AppRun script? It seems like AppRun is a Rox alternative to .desktop and a folder full of RoxApps is functionally equivalent to a start menu or a desktop.

Those portable apps you shared do look handy. If I understand correctly, the advantage is that you can run them with rox and there is no need for a .desktop file to be added to the system. Furthermore, if you study the behavior of the app and "install" the RoxApp like Duprate does then the app cache and data can be symlinked back into the RoxApp folder, but that behavior could be replicated with an install.sh and a .desktop file.

I am not writing this to be disagreeable. It seemed to be exactly on topic since AppRun and .desktop do such similar things and since distributed apps such as pburn aren't even referencing the RoxApp the way Williams2 described.

I will start another topic to ask about the seamonkey-spot script.