Coding for EasyOS

Page originally written: December 21, 2019
Updated: August 23, 2022; September 19, 2022

This is a page for developers, anyone who creates applications, utilities, or systems-level scripts, in a variety of languages, from shell script to compiled languages. If you are interested in getting involved in EasyOS development, read on...

I, Barry Kauler, am writing this page in the first-person, for more personal interaction. Any questions, there is a "Contact me" link at the top of this page -- though do note, although I read all messages, I don't always reply, or a reply might be delayed -- this is just a question of efficiency of time, and do recognise that I consider all suggestions, and often have to file them away for future consideration.

There were lots of development documents created for Puppy Linux, now archived here:

https://bkhome.org/archive/puppylinux/development/index.html

EasyOS inherits a lot of "puppyisms", so large chunks of those documents are still relevant. However, the page you are reading now brings things up-to-date for EasyOS. Incidentally, I often refer to EasyOS as just "Easy".

Now for some headings to break this page up...

Getting setup for development

It is not necessarily required for shell scripting, but certainly to compile C/C++/BaCon code, access git and svn repositories, etc., you will need to have the "devx" SFS loaded.

Easy, like Puppy, provides everything needed for development in a single SFS file. Easy runs as a layered filesystem, with read-only 'easy.sfs' on the bottom and a read-write folder (/mnt/wkg/.session) on top. Other SFSs can be inserted between these two, such as the "devx" SFS.

To obtain the "devx" SFS, click on the "sfs" icon on the desktop, and there will be an offer to download and install it. You will be asked whether to install it into a container or the main desktop -- choose the latter, as compiling inside a container does require a bit more thought and some caveats.

A reboot is then required, as the Aufs layered filesystem is created in the initrd. After reboot, type "which gcc" in a terminal, to confirm that yep, the devx is loaded.

Choice of language: script

Most coding in EasyOS is Bash/Ash shell scripts, from system-level scripts up to sophisticated GUI applications. Ash is the shell interpreter provided by Busybox, and is often preferred as faster than Bash, and has many "bashisms" (and has many more features than 'dash' used in Debian).

Bash/Ash is fairly easy to learn, and a good way to get into coding for Linux, any Linux, not just EasyOS. In fact, it is my recommendation for anyone who asks the question "What language should I learn for coding in Linux?".

You can create surprisingly sophisticated GUI apps in Bash/Ash. Mostly we use gtkdialog to provide the GUI frontend. Documentation for gtkdialog  is found at /usr/share/doc/gtkdialog

I also highly recommend this thread on the Old Puppy Forum, "GtkDialog - tips" created by zigbert:

https://oldforum.puppylinux.com/viewtopic.php?t=38608

There are a host of other tools useful for GUIs with shell scripting. Just listing some here, you will have to chase up documentation on each. These are all builtin to Easy, without needing the devx SFS:

Xdialog, xmessage, pupmessage, pupdialog, popup, yaf-splash 

...well, you can just type the name in a terminal, ENTER, or append "--help", for information.

Choice of language: compile

Puppy and Easy developers write some utilities in C. Examples are the pup_event mechanism and some systray applets such as the temperature and memory applets.

There are also some utilities written in BaCon, and very recently, Nim:

	BaCon is a BASIC compiler -- well technically not a compiler -- it translates BASIC code to C and then calls gcc. You might find BaCon an easier way to get into compiled coding than C. Here is an introduction to BaCon, with a link to an example GUI application: https://easyos.org/dev/bacon/index.html
	Nim is also a translator, generating C, C++ or Javascript. Here is an introduction to Nim: https://easyos.org/dev/nim/index.html

Continuing with C/C++ compiling...

If you download a source package from somewhere, written in C or C++, and want to compile it, you do the usual steps. However, perform the final "make install" a bit differently:

# ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --build=x86_64-pc-linux-gnu etc 
  OR, if source uses cmake:
  # cmake . -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_SYSCONFDIR=/etc
# make
# new2dir make install

What that last step does is perform the installation, but also creates a folder with all of the installed files. It does require that the folder of the source code is of the format "<name>-<version>", which is the usual case -- but if it isn't, like if it is just a name without version, rename the folder before performing the configure and compile steps.

One other thing: very occasionally 'new2dir' doesn't work, or works incorrectly. That is a very unusual situation, with a very odd Makefile, but it can happen. In that case, you will have to do the normal "make install".

"make install" hint:
If you were forced to do a "make install" and want to find all the installed files. A quick way to find them is to look in /mnt/wkg/.session (or /mnt/.easy_rw/mainrw) -- this is the read-write layer of the aufs layered filesystem, that is, it contains the current session. You could copy these files to manually create a PET, however, be careful that you do not copy any '.wh..*' files -- these are "whiteout" files used by aufs. 

Not just 'new2dir', there are other very handy little utilities for developers. Tabulating them:

Script	Example	Description
dir2pet	dir2pet abiword-2.5.6-amd64	Convert a directory to a PET package
new2dir	new2dir make install	Create a directory of installed files
pet2tgz	pet2tgz abiword-2.5.6-amd64.pet	Convert .pet to .tar.gz tarball
pet2dir	pet2dir aiword-2.5.6-amd64.pet	Convert a .pet to a folder
dir2tgz	dir2tgz abiword-2.5.6-amd64	Create a tarball from a folder
tgz2pet	tgz2pet abiword-2.5.6.tar.gz	Convert a .tar.gz file to PET package
dir2sfs	dir2sfs abiword_2.5.6_amd64	Create a SFS from a folder
deb2sfs	deb2sfs abiword_2.5.6_amd64	Create a SFS from one or more DEBs

PET packages are the native package format used in Puppy and Easy, though other formats such as Debian and Ubuntu DEB packages are also handled by the PKGget package manager (also known as the "PPM" -- from the Puppy days, we called it the "Puppy Package Manager").

After having run the "new2dir make install" step, you can then run "dir2pet <folder name>" to create a PET package.

Note that 'tgz2pet' is dumb, it just appends a checksum onto the tarball and renames it to .pet. Certain meta-data that is expected to be inside the tarball is not created. To create a .pet package correctly, use 'dir2pet'.

Note, if you had opened up a PET with 'pet2dir' (in a terminal or via right-click on the PET), it can be closed up again as-is with 'dir2tgz' and 'tgz2pet'.

Some very old information about PET packages is here:

https://bkhome.org/archive/puppylinux/development/createpet.htm

...though note that the ".specs" file inside the PET is now just named "pet.specs".

You can also create an SFS file from a folder. If you have compiled an app and installed with "new2dir make install", you will have a folder, and you can do this:

# dir2sfs <name of folder>

However, the folder must be named in a certain format, "name_version[-revision]_architecture", for example "abiword_2.5.6_amd64". Here is a blog post that introduces dir2sfs:

https://bkhome.org/news/201811/dir2sfs-take-2.html

Another handy hint, make sure that there is "<name>.png" in usr/share/pixmaps in the folder, as this will be used as the icon for the container on the desktop. If you don't have that PNG, dir2sfs will try to find it, and might find an inappropriate image.

To try out your SFS, copy it to /mnt/wkg/sfs/easyos/<compatible distro>/<distro version>/ (ex: /mnt/wkg/easyos/debian/buster), then run menu "Filesystem -> Easy Boot Manager" and click on the "Load extra SFS files" button.

...well, that does require it not be already installed, so you might have to try on a different installation of Easy, or run "make uninstall".

Note, it is useful to take a snapshot of the session before compiling, which you can roll back to afterward. To create a snapshot, go to the menu "Filesystem -> Easy Version Control" and click the "Snapshot" button. This is great, as you can wipe out everything installed. The source code that you compiled would normally be somewhere else, in a partition somewhere, so not in the .session folder, so will not be affected by snapshot and rollback. 

Menu hierarchy

It is appropriate to mention on this page, as if you create a PET, you will want an entry in an appropriate place in the menu.

The menu hierarchy is different from other Linux distributions. Some users like it, some don't, but it is what it is and you have to live with it. Actually, it is the mere fact of being different that causes initial user resistance, but in time it is found to be OK.

Puppy and Easy have singular hard-coded menu placement. That is, an app can only appear in one place in the menu. The .desktop file, found in /usr/share/applications, has an entry "Categories=", and Puppy/Easy only require one value.

For example, /usr/share/applications/asunder.desktop has this:

Categories=X-Multimedia-sound

To find a suitable value for the "Categories" parameter, look at this file: /etc/xdg/menus/hierarchy

A couple more hints about creating a Easy-friendly .desktop file:

Exec=asunder	Do not preppend a path, nor append anything
Name=Asunder audio CD ripper	Format: <name> <short description>
Icon=asunder.png	Usually no need for a path

Regarding the "Icon" parameter, Easy looks in /usr/share/pixmaps, /usr/local/share/pixmaps, /usr/local/lib/x11/mini-icons, /usr/local/lib/X11/pixmaps. If anywhere else, a path is required. 

Tags: dev