Salta al contenuto principale

EasyOS

Image
logo

EasyOS è nato a gennaio 2017, e da allora sono stati scritti qua e là pezzi su come e perché è diverso dalle altre distribuzioni Linux. Ciò include alcune descrizioni piuttosto tecniche.

Tipo Sistema Operativo
Linux


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

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

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

Distro


Why the ISO format has to die

Page originally created December 28, 2021
Updated: November 14, 2022

EasyOS ships as a .img file, that is written to a drive. Barry stopped shipping EasyOS as an ISO file from early 2020. This was a controversial decision. Barry will continue the rest of this page writing in the first-person.

When I first wrote this page, in December 2021, I was reacting to emails that I had received. Quite incredible emails; one guy told me it is not my fault, I am showing the signs of early dementia!

My reaction below, is somewhat confronting, but it represents my mood at the time. Revising this page in November 2022, I decided to leave that text as-is...


I maintain that the ISO format has "had it's day" and needs to be retired. Furthermore, I claim that the image format is simpler and easier to use; however, some Linux "old timers" claim the opposite.

I saw their entrenched obstinacy as akin to my elderly step-mother sticking with audio cassettes and keyboard flip phone. So finally, in December 2021, I decided to clarify my claim in a blog post:

https://bkhome.org/news/202112/why-iso-was-retired.html

I also started a thread on the Puppy Forum for feedback, and as a consequence wrote a follow-up blog post:

https://bkhome.org/news/202112/why-iso-was-retired-part-2.html

If anyone reading this feels that they would like to contribute an opinion, here is the forum thread:

http://forum.puppylinux.com/viewtopic.php?t=4690

However, please do not just post your pre-conceived prejudices and narrow understanding.

Misunderstandings are OK, as long as the person is willing to learn.

For example, someone sent me an email yesterday (December 26, 2021) asking if they needed to format the usb stick with an ext3 or ext4 partition before writing the 'easy-3.1.17-amd64.img.gz' (latest release at time of writing) file to the drive. I replied that it doesn't matter what is on the drive beforehand, just use Etcher or easydd or some other tool that will write the image file to the usb-stick, then boot from the stick and you are good-to-go.

A note to anyone reading this, who needs help on how to use tools like Etcher or easydd, see this page:
https://easyos.org/install/how-to-write-easyos-to-a-flash-drive.html

That person was willing to learn and did follow my instructions. Unlike the entrenched "pro ISO" elderly Linux users, who just "dig their heels in" and re-state their fossilized opinions.

I will make one more statement. I received an email recently, the person stated that they understood ISOs and just didn't want to have to learn something different. This attitude is common among the elderly Linux users. The funny thing is, there isn't much to learn to make the switch to image format. The one area of difficulty is opening up an image file if one wants to extract the contents (vmlinuz, initrd, easy.sfs); however, that difficulty only applies to legacy Linux distributions, not to EasyOS.


Fast forward to November 2022, editing this page, I will add a more fundamental reason why I don't want to release EasyOS on an ISO anymore: it undermines what Easy is all about.

What I mean by that, is all of the documentation about Easy, and the features of Easy, are based on the layout of a boot-partition and a working-partition, whether it be in a USB-stick or installed in internal partitions.

If there was a live-CD, I would have to put in conditions throughout the documentation, like "except that you cannot do that if booted from a live-CD". The behaviour having booted from a live-CD is very different, and it adds up to a maintenance overhead, meaning it takes up my time.

There are only so many hours in the day. I have a tendency to get enthusiatic about something new, then get burnt out and have to wind back. Easy is, essentially, a one-person project, and I have to remain focussed on what is really needed.      

Tags: about

Distro


Limine bootloader

Page created July 25, 2022
Updated: November 28, 2022

Those who have installed Linux on a computer will know of GRUB, GRand Unified Bootloader, of which there are two versions, the predecessor that we now know as GRUB-Legacy and the current version, that we know as GRUB2.

GRUB-Legacy, and a variant, Grub4dos, are for BIOS-firmware x86 32-bit and 64-bit computers, whereas GRUB2 handles BIOS-firmware and UEFI-firmware computers. The latter are most x86 desktop computers and laptops manufactured since 2012.

There are other less-known bootloaders. One notable is rEFInd, which is for UEFI computers only. There are others, such as Syslinux and Clover. Some of these, such as Syslinux, have been around for a very long time.

There is a newcomer, first release in April 2020, named Limine, that, like GRUB2, supports BIOS and UEFI computers, 32-bit and 64-bit. Limine is very small, and arguably contrary to GRUB2, easy to install and use.

Limine has been adopted as the official bootloader for EasyOS, and is included in every release from 4.2.8 onwards.

EasyOS also includes a GUI frontend for Limine, named "Limine Installer", found in the "Setup" category of the menu.

Port Limine Installer:
You can use Limine Installer in a different Linux distribition. It is not available as a package; you will need to obtain the individual files from the woofQ project on github (woofQ is the build system for EasyOS). Here are the scripts, at /usr/local/limine-installer:

https://github.com/bkauler/woofq/tree/main/easyos/easy-code/rootfs-skeleton/usr/local/limine-installer

Script to run the installer, at /usr/bin:

https://github.com/bkauler/woofq/blob/main/easyos/easy-code/rootfs-skeleton/usr/bin/limine-installer

Menu entry:

https://github.com/bkauler/woofq/blob/main/easyos/easy-code/rootfs-skeleton/usr/share/applications/limine-installer.desktop

And an icon:

https://github.com/bkauler/woofq/blob/main/easyos/easy-code/rootfs-skeleton/usr/share/pixmaps/limine-installer.png 

If you want to install EasyOS to an internal drive in a computer, you will need a ext4 partition, to which you copy the three files 'vmlinuz', 'initrd' and 'easy.sfs', and that will become the "working partition". Also, a boot-partition is required, to install a bootloader -- and that can be GRUB2, rEFInd, Limine, or whatever.

Exactly how the previous paragraph is implemented, depends on various factors, but if you would like to get a quick appreciation, using Limine, see this tutorial:

https://easyos.org/install/how-to-install-easyos-on-a-new-ssd.html

...in that case study, the EasyOS image file already has the Limine bootloader.

However, there are other situations, such as a computer that has Windows and one (or more) of the mainstream Linux distributions installed, dual-booting. In that case, most likely the GRUB2 bootloader was installed.

Or, the computer may only have Windows. In that case, you either install another drive, as in the above case-study, or you have to create a ext4 partition in the existing drive, and maybe a second vfat boot partition.

The intention of this page is to be a jumping-off point, to pages that show how Limine can be installed and used in these different hardware and installed-OS situations.

Limine project

Firstly, here is the Limine project page:

https://github.com/limine-bootloader/limine/tree/v3.0-branch 

Now for some usage scenarios...

BIOS computer with Grub4dos

This link shows Limine Installer being used to install Limine to a BIOS computer, that already has Grub4dos bootloader and various Linux installations:

https://bkhome.org/news/202207/limine-installer-version-10.html

...Limine has replaced Grub4dos. But note, it is possible to revert back to Grub4dos.

UEFI computer with Windows 10

This link shows Limine being installed to a UEFI computer that has Windows 10 and EasyOS installed, already with the rEFInd bootloader:

https://bkhome.org/news/202207/testing-limine-installer-on-a-uefi-computer.html

...Limine has replaced rEFInd. Again, it can be reverted.

UEFI computer with mainstream Linux distros

Originally, it had Windows, that was removed, and currently has two frugal installations, EasyOS and VanillaDpup, and three mainstream-Linux installations, Debian, Mint and Manjaro. The mainstream distros all installed GRUB2. Link showing Limine being installed on this computer:

https://bkhome.org/news/202207/install-limine-to-pc-with-mainline-linux-distros.html

...as stated in that post, Limine was installed to /EFI/limine/BOOTX64.EFI, and the UEFI-Setup set to make that the default boot choice. Also easy to revert, by removing that .EFI file.


more tutorials to come!


Support

Limine and the Limine Installer are not restricted to be used on EasyOS. Both will work on any 32-bit or 64-bit Linux OS. Further discussion is at the Puppy Forum:

https://forum.puppylinux.com/viewtopic.php?t=6406

https://forum.puppylinux.com/viewtopic.php?t=6910

https://forum.puppylinux.com/viewtopic.php?t=6284

    

Tags: install

Distro


How Easy works

Page originally written September 24, 2017
Partially updated: December 20, 2018
Major update: November 12, 2022
Updated: April 2, 2023. April 8, 2023 

EasyOS is a "new paradigm" for a Linux distribution, a blend of the best ideas from Puppy and Quirky, and a fundamental rethink of the security, maintainability and ease-of-use.

A good way to explain what Easy is all about, is to follow the user (that's you) experience, from downloading the deployed file, to installing and discovering it's features. To start, you would go to one of the websites hosting EasyOS and download it...

Download

Unlike most other Linux distributions, Easy is not deployed as a CD/DVD disk (ISO file). Instead, Easy is an image for an entire drive, such as USB Flash stick, SD-card, HDD, or solid state disk (SSD).

One might immediately counter that ISO files can also be written to Flash media -- yes, but that is not an installation -- the distribution still has to be installed somewhere. With Easy, what is written to the Flash media is the installation, nothing more to be done. You can run Easy from external media indefinitely, but there is also the option of installing to internal drive.

The file you download is named easy-<version>-<architecture>.img, at the time of writing the latest is easy-5.2.1-amd64.img. You can find the latest here, courtesy of ibiblio:

https://distro.ibiblio.org/easyos/amd64/releases/kirkstone/

Or this mirror site, courtesy of NLUUG:

https://ftp.nluug.nl/os/Linux/distr/easyos/amd64/releases/kirkstone/

If all that you know is ISO files, then you might not know how to write a drive-image file to a USB-stick. If that is the case, read this page:

https://easyos.org/install/how-to-install-easyos-on-a-new-ssd.html

It is really quite simple. You write the image file to a USB-stick, then persuade the computer to boot from the USB-stick, bootup and you have a desktop:


img1

The file easy-5.2.1-amd64.img (or whatever version you have downloaded) is an image file, that can be written to any drive. Although it is only 825MB, at first bootup it will expand to use the entire drive. So any drive, from 8GB upwards, is suitable (although at least 16GB is recommended for ongoing usage).

Internal structure of the image file

Internally, the image file looks like this:

Gap
1MiB
Boot-partition
7miB fat12
Working-partition
816MiB ext4    
Gap
1MiB

If you are running EasyOS, you can just click on the file, and both partitions will be automatically mounted and opened in the file manager. This is the 7MiB vfat partition:

img2

And the 816MiB ext4 partition:

img3

If you are running some other Linux distribution, you will have to calculate the offsets and mount the partitions manually, as described in this page (near bottom of page):

https://easyos.org/user/how-to-update-easyos.html

Easy is extremely easy to install to an internal drive, as it consists of only those three files easy.sfs, initrd and vmlinuz, and need only occupy one folder in a ext4 partition, leaving the rest of the partition free for whatever else is already there, such as another Linux distribution.

All that you have to do is create a folder in the ext4 partition of the internal drive, copy those three files to it, and hey, installed!

There is one important detail of course; how to boot it. If you already have GRUB or rEFInd or some other boot-loader installed, another entry can be added to boot Easy.

Or, you can install the Limine boot-loader, which is very simple and handles both UEFI and older legacy-BIOS computers. Easy has "Limine bootloader installer", found in the "Setup" menu. Limine is introduced here:

https://easyos.org/install/limine-bootloader.html

...be careful though, the Limine Installer is still a work-in-progress. Perhaps try it on a computer that you don't mind if something goes wrong.

Taking a closer look at the bootup process...

The Limine boot-loader

Any boot-loader can be used. The EasyOS image file comes ready-made with Limine in the 7MiB vfat partition. The boot-loader is what the BIOS or UEFI passes control to at bootup, and it usually contains a menu for booting multiple OSs. When you boot the USB-stick, you will just see the one entry, to boot EasyOS (for the example of the EasyOS Dunfell-series, that precedes the Kirkstone-series):

img4

However, it is a boot-loader, and it can boot anything. See the file limine.cfg in above snapshot of the vfat partition; edit that to add entries for more OSs, Linux, BSD, Windows, whatever.

The same principle holds if you were to install Limine to the internal drive. It would be required to read the Limine documentation to know how to edit that file, but the "limine bootloader installer" in EasyOS does a pretty good job of finding installed OSs and creating a limine.cfg for you -- though, as mentioned above, that is still a work-in-progress.

When the "EasyOS dunfell" entry is chosen, the boot-loader then loads the linux kernel vmlinuz and the file initrd.

Files initrd and easy.sfs 

As already stated, the boot-loader first loads the Linux kernel, vmlinuz, then the "initial-ramfs", file initrd. File initrd is a complete tiny Linux operating system, whose main job is to setup the EasyOS desktop and switch to it.

At the very first bootup, it asks for a password. This is optional. You could just press the ENTER key, no password; however, this is not recommended. A password is recommended, anything you want that is easy to remember, and it will encrypt some folders in the working-partition. Extremely important in case your USB-stick is stolen!

The downside is that you have to enter the password at every bootup. The initrd also has an optional menu:

img5

Normally, you would just type in the password, press ENTER, and the initrd would proceed to setup everything to switch to the desktop...

The initrd uses "aufs", which is a layered filesystem. Essentially what this does is stack folders one on top of the other. This should help to visualize what happens:

/
this is the abstraction, view at the top
RW layer folder
this is the .session folder in the working-partition
RO layer folder
easy.sfs is mounted on this folder

where "RW" means read-write and "RO" means read-only.

File easy.sfs is the entire EasyOS. It is created with the "squashfs" filesystem. When mounted on a folder, you see the entire filesystem.

File easy.sfs is quite big, typically about 750MB. If, for example, it contains file /usr/share/doc/help.htm, that will appear at the "/" top -- except if there is another /usr/share/doc/help.htm in the RW layer, then the highest file is what you will see at "/".

That RW layer can also "erase" files and folders in a lower layer, or rename them, by means of what are known as "whiteout files". That is not a detail that need concern you -- if for example, from your perspective at the the top "/", you delete /usr/share/doc/help.htm, it will disappear. You don't need to know the wizardry underneath.

When you are running EasyOS, any changes that you make, such as installing packages, or creating and editing files, will all go into that RW layer.

The above visualization is, however, not correct in Easy's default mode at bootup. That .session folder is in the working-partition; however, to minimize writes to the Flash media, an indirection was introduced with Easy 4.4, visualized like this:

/
this is the abstraction, view at the top
RW layer folder
this is a folder created in the RAM
RO layer folder
easy.sfs is mounted on this folder

Instead of writing directly to the .session folder in the Flash media, an ext2 filesystem is created in a "zram" device. Zram is compressed-RAM, in other words, everything in it is compressed, meaning that a lot more files can be stored in it than the actual size allotted to the zram in the RAM.

Ok, again, don't worry about the underlying wizardry, just see the end result; the RW layer is now in RAM, so all writes are now only happening in RAM, not to the Flash media.

However, we cannot get away from eventually having to write those files to the .session folder, and this can be done at any time you want, via the "save" icon on the desktop, or at shutdown.

Scroll back up to the snapshot of the desktop, you will see the "save" icon.

This indirection has another benefit; you may bootup, surf the web, then shutdown, without saving and without leaving any trace of what you did during that session.

The traditional mode, prior to easy 4.4, was to mount the .session folder directly on the RW layer, and you may go back to this if you wish -- it is offered as a choice via the "save" icon.

Direct write to the .session folder might be OK for a HDD or a high-quality SSD, where you don't mind the drive getting hammered with writes.

Anyway, getting back onto what the initrd does...

The layered-filesystem is setup, with that "/" on top, and at the final step there is what is called a "switch_root", which transfers from the tiny Linux OS in the initrd, onto the "/" top of the layered filesystem.

This switch_root is magical. After it happens, suddenly this is what the filesystem looks like:

img6

...what you are seeing here, is everything in easy.sfs, plus any new files created in the RW layer overlaid.

After that switch_root, the /sbin/init script executes, which ends up running the Xorg graphics server and the desktop is launched.

Looking inside initrd and easy.sfs

This section is for the technically-minded. If you would like to poke around inside those files, it is quite easy to do.

Running EasyOS, all that you need to do it click on those files, and they will be opened up. The initrd file can be opened up, you can edit anything inside it, then click again on the initrd file to update and "close" it. The easy.sfs file can also be opened, but it is RO.

Alright, go to the working-partition and click on initrd, there is a dialog window asking if you want to open the file, you answer in the affirmative, and a file manager window pops up:

img7

img8

img9

...some of the scripts shown above were experiments, not currently used. For example, startx and xinitrc started a tiny Xorg server in the initrd, for the purpose of running GUI apps prior to the switch_root.

And yes, you can also click on easy.sfs and view its contents, read-only. If you scroll back up, you will see where it is, in the working-partition, or more precisely at /mnt/${WKG_DEV}/${WKG_DIR}easy.sfs, which resolves to /mnt/sdb2/easyos/easy.sfs in the example.

Note, those variables WKG_DEV and WKG_DIR are defined in file /etc/rc.d/PUPSTATE

However, there is a gotcha, as after the first bootup, easy.sfs will no longer be there. At first bootup, the initrd creates some folders in the working-partition and easy.sfs is moved elsewhere:

img10

...the file manager has been set to show hidden files and folder, and you can see the .session folder. But no easy.sfs.

File easy.sfs has been moved and renamed, for the example of EasyOS 5.2.1 Kirkstone-series, to /mnt/sdb2/easyos/sfs/easyos/oe/kirkstone/easy_5.2.1_amd64.sfs

...as to why that is done, that is a whole other story, that will require its own web page. In summary though, it is an organizational thing, to have all SFS files under the sfs folder -- it greatly aids rollback, roll-forward, and usage of SFS files in containers.

How Easy works after switch_root

After the switch_root has occurred, Easy-proper is running. "How Easy works part-2" focuses on how Easy works, and usage, after the switch_root:

https://easyos.org/tech/how-easy-works-part-2.html



(c) Copyright Barry Kauler, December 2018,2022,2023, all reproduction rights reserved.
Disclaimer: Barry Kauler has provided these instructions in good faith; however, there is a disclaimer of all responsibility if something does go wrong. It shouldn't, but if you type in something incorrectly and wipe your C: drive, that is entirely your own responsibility. 

Tags: tech

Distro


How Easy works, part 2


Page originally created December 20, 2018
Page updated: November 12, 2022. April 2, 2023. April 8, 2023

How Easy works part-1 is here:

https://easyos.org/tech/how-easy-works.html

Part-1 examines bootup, until "switch_root". Part-2 continues, from after bootup has completed and we have the desktop. Part-2 is useful from the usage point of view; however, it is worthwhile to scan through part-1 and pick up the salient points.

The layered filesystem

Recapitulating, here is a visualization from part-1, showing the layered filesystem just after bootup:

/
this is the abstraction, view at the top
RW layer folder
this is a folder created in the RAM
RO layer folder
easy.sfs is mounted on this folder

As explained in part-1, the RW layer is a zram device in RAM, and it needs to be saved to the .session folder, at any time while running Easy, or at shutdown. Or, if you don't mind the drive being hammered with writes, the .session folder can be mounted directly on the RW layer folder:

/
this is the abstraction, view at the top
RW layer folder
this is the .session folder in the working-partition
RO layer folder
easy.sfs is mounted on this folder

Also as explained in part-1, the image file that you download and write to a USB-stick, has a vfat boot-partition, with Limine boot-loader installed in it, and a ext4 working-partition, that has the EasyOS files vmlinuz, initrd and easy.sfs.

At the first bootup, the initrd increases the size of the working-partition to fill the drive, and creates some folders in it, and moves easy.sfs into the sfs folder. This is what the working-partition looks like after bootup:

img0

Right-click in the window, the menu has an entry to show hidden files and folders (they start with a "."):

img1

...showing the .session folder, where that RW layer gets saved, and the sfs folder where easy.sfs got moved to.

Part-1 also explained that the aufs layered filesystem has created "/" with RW and RO folders underneath. if you start the file manager and look at "/". this is what you see:

img2

A way to conceptualize this "/" is to see it as an an abstraction, a contrivance, created in RAM.

If you were to create a file, say /usr/share/doc/test.txt. That will actually be created underneath, in the RW layer, and if you choose to save, will end up in the .session folder.

Or, if you do not save, it will disappear at shutdown.

However, there is one exception; the /files folder. That folder is linked to the files folder in the working-partition, so anything created under /files is actually created in the working-partition. From the above example, that is /mnt/sdb2/easyos/files

To be more technically correct, /mnt/sdb2/easyos/files is "bind mounted" on /files

The reason for doing this is that most apps default to open|save|download to /files, so if for example you save a web page from the browser, or download a file, it will be saved under /files, so is immediately saved.

Thus, /files is the place for all your personal files. There is a folder hierarchy under /files:

img3

Different apps will default to save in different places under /files, for example mtPaint will default to save images to /files/media/images

Other special features of /files:

  • Apps in containers are isolated from the main filesystem; however, /files/shared inside the container is linked to /files/shared in the main filesystem. This is a convenient way for an app in a container to export a file to the "outside world".
  • Any app may be run non-root. For example, Firefox runs as user "firefox", with home folder /home/firefox. Firefox does not have write permissions outside its home folder; however, it does have permission to save to /files

Now to examine further what is in the working-partition...

The working partition

Staying with the example of booting off a USB-stick which is /dev/sdb, with sdb1 being the boot-partition and sdb2 the working-partition. Here is an example of how the partition icons will look on the desktop:

image9

The solid-orange rectangle marks the working-partition, and under normal conditions it cannot be unmounted as it is in use.

The rectangle with a cross in it is a mounted partition that can be unmounted -- which is achieved by clicking on the cross.

If you click on the sdb2 icon, it will open in the file manager, and you will see /mnt/sdb2, with folder easyos. Then if you click on easyos, you will see what is inside -- see snapshot back up this page. Well, here it is again:

img4

Incidentally, that folder name "easyos" is an arbitrary name. It could be any name, or deeper in the hierarchy, for example "easyos/dunfell"

That folder name is variable WKG_DIR, that you can see in /etc/rc.d/PUPSTATE

The WKG_DIR is specified at bootup, in the limine.cfg boot-loader configuration file.

Here is a summary of some of those folders:

containers

This is where applications can be run in isolation. Each container is a layered filesystem, very similar to the main one, with RO layer easy.sfs, and a RW folder. Additional SFS files may be loaded as RO layers, for example the "devx" SFS for compiling source packages (Puppy users will know all about that!). Containers serve two purposes, isolation and/or security.

files

Easy, like Puppy, is a single-user system. With Easy, /files is where you store all your "stuff". Downloaded files, photos, videos, anything.
And as previously stated, /files is actually a link to folder files in the working-partition.
It is a work-in-progress to get the apps in Easy to open in the /files folder whenever "File -> Open..." (or Save, or Download) menu operation is performed.

releases

This is an archive for Easy versions and snapshots. For example, if you upgrade from version 4.4.3 to 4.5, all of version 4.4.3 is saved in folder releases/easy-4.4.3, and you can at any time roll back -- the menu "Filesystem - > Easy Version Control" handles this.

sfs

All SFS files are kept in here, to keep them nicely categorised and avoid duplication.

Note, there will be two more folders, 'appimage' and 'flatpak', that are created if an AppImage or a Flatpak package is installed.

What follows are various usage technical topics. Not exhaustive, and it will be helpful to read other web pages at easyos.org

Upgrade, snapshots, rollback

Upgrading, snapshot and rollback is now a separate tutorial:

https://easyos.org/user/easy-version-upgrade-and-downgrade.html

In a nutshell, it is very easy to upgrade and to rollback.

As the above link explains, there is a nice GUI to manager roll-back and roll-forward. Reproducing a snapshot here:

image5

...which shows after upgrading from 0.9.13 to 0.9.14, and a snapshot was taken in 0.9.13. Roll-back and roll-forward can be to any of these.

You can take a snapshot at any time. All that this does is save the current .session folder, the RW layer, as a file named rw-<date>.sfs, in the releases folder.

Obviously, saving a complete record of past versions is going to occupy a lot of the working-partition. However, the history is saved as compressed SFS files. To avoid the history growing to fill all of the partition, there is a maximum depth setting, set to "3" in the above photo -- meaning that only the current version and two prior are kept. But any number of snapshots within that depth limit.

Another thing to consider, is that /files is outside of this rollback/snapshot mechanism. /files is where you can keep all your personal files. Downloads, videos, photos, etc. Try and put as much as you can in here, instead of bulking up the .session folder.

releases folder

All of the files belonging to a particular version of Easy are in a sub-folder inside the releases folder, for example releases/easy-0.9.10. If you were to look inside one of these sub-folders, this is indicative of what you would see:

image8

The configuration files have various configuration variables. SFS file devx.sfs is familiar to Puppy users -- it contains everything to turn Easy into a compiler environment, and can be selected to mount as a layer at bootup. Extra SFS files such as devx.sfs are optional, and can be selected to be added to the layered filesystem at bootup.

It is very easy to add, or remove, an extra SFS file to/from the layered filesystem: see the menu "Filesystem -> Easy BootManager":

image8

...a ticked checkbox will mean it is already loaded.

sfs folder

Notice in the above snapshot, the sfs folder, and in second-from-last "easy.sfs" and "devx.sfs" are symlinks. The purpose of sfs folder is to keep all of the SFS files organised, into categorised sub-folders, and to ensure there isn't unnecessary duplication.

Here is a picture of one such sub-folder under sfs:

image9

Downloading and installing of SFS files is managed via the "sfs" icon on the desktop.

Encryption

The init script, the first thing executed at bootup, as explained in part-1, has an option to encrypt folders in the working-partition.

What the init script does, is ask for a password. If the user decides to provide one, then the containers, releases, home and .session folders in the working-partition are encrypted.

This can only be done when the folders are newly created, with nothing in them. From then on, at every bootup, the password must be entered to unlock them.

The encryption mechanism is provided for the ext4 filesystem, using "fscrypt", which is a feature built-in to ext4. It provides AES-256 encryption.

Note that the sfs folder is not encrypted. This is because there is no point in encrypting the SFS files, and doing so would only slow down operation.

So, what does a folder look like if you don't have the password to unlock it? Here is an example::

imagex

Note that the password entered at bootup is also assigned as the password for "root" and "zeus" users.

Moving on, Easy is designed from scratch to support containers...

Easy containers

Easy has been designed as "container friendly". It was carefully considered how containers would fit in, that is, be highly integrated with the rest of Easy, extremely easy to setup and use, and be very efficient.

There are ready-made container solutions out there, such as LXC and Docker, however, for now Easy is built with a "homebrew" container. The Author is far from being a security or container expert, but for his own satisfaction wanted to play with containers created from basic principles.

Starting by looking at containers already created in the currently running Easy. ROX-Filer shows the containers folder in the working partition, for the Dunfell-series of EasyOS:

image10

Burrowing down, looking inside the www folder:

image11

See also the "dunfell" container. This is a container for to run the entire Easy desktop in a container. It runs as a layered filesystem, just like the main Easy filesystem, with easy.sfs on the bottom, a read-write layer, and the "top" (the container folder).

But, back-tracking for a moment. How did the dunfell container get created? And how to run it?

Well, Easy is setup so that dunfell, console and www are pre-created, however, it is very easy to create a container for any application -- there is a nice GUI, called Easy Containers.

It is launched via the Filesystem menu:

image15

Here is a snapshot:

image12

An existing container can have its behaviour modified, or be deleted, as shown.

To create a new container, it is just a matter of selecting an app from the drop-down list, choose appropriate security options, then click the "Create" button.

There is help available for making the best decisions regarding security, but also there are templates that will preset the checkboxes when you choose an app.

Technical note: these templates are located at /usr/local/easy_containers/templates

A desktop icon is automatically created. These are the pre-created container icons, for the Dunfell-series:

image13

And for the Kirkstone-series:
img10

...just click on an icon to launch it!

Furthermore, a new menu entry is automatically created, just like this one for Firefox:

image14

...two Firefox entries. You can choose to run it normally or in the container.

Note the special icon used to denote apps that run in a container.

Extra notes about Firefox security:
Even when running normally, on the main filesystem, it is running as user "firefox", so has the safety of being non-root. Also Firefox has its own sandbox. So this is one situation where running on the main filesystem might be almost as secure as running in a container.

There isn't anything more to say, that's it, container created and ready to use.

What actually happens if you select that containerized Firefox entry in the menu, is that it executes "ec-chroot firefox", instead of just "firefox".

ec-chroot is a script, found in /usr/local/easy_containers/. In a nutshell, it will "start" the container, then chroot into it and run the app.
By "start", it is meant that the layered filesystem will be setup. ec-chroot calls another script to do this, named start-container.

When the app terminates, or the container is in other ways exited, ec-chroot calls stop-container, which kills all processes running in the container and unmounts everything.

This technical description of container scripts is only mentioned if you are interested. For someone who is just a user, the GUI does it all, and very simply.

A note about the efficiency of Easy Containers. There is virtually no overhead to add a container. No files are duplicated. The same easy.sfs is used as for the main Easy Linux.
Of course, running an app in a container, it will create its own cache files and so on.

The container layered filesystem

What is the point of running an app inside a container? Thinking about the user, who isn't concerned about the technical details, just what practical benefits the container concept brings, or what problems.

Broadly, there are two reasons, one, to provide isolation from the rest of EasyOS, and second, security. A diagram helps here, to show the filesystem you have access to while running in a container:

image16

The example is for a container named seamonkey. easy.sfs is mounted on folder .ro0 and this becomes the bottom read-only layer (also, there can be more RO layers). Actually, this example was written during the EasyOS Pyro-series, before the Dunfell-series, and SeaMonkey was the default browser, builtin to easy.sfs. The Dunfell-series adopted Firefox as the default, builtin to easy.sfs, and now the latest, the Kirkstone-series has Chromium builtin.

If SeaMonkey, Firefox or Chromium was not builtin, it can be provided as an SFS, in which case it can be mounted as another RO layer above easy.sfs.

The folder .session is RW, and the user's view in the running container is folder container. This was already explained, however, think about it...

The app running in the container, or any file manager or terminal emulator, will only be able to see the files in folder container. Which is the content of easy.sfs and any changes made on the rw layer. That's it, the rest of the system is just not there.

Yet, as folder .session is just a folder in the working partition, the entire storage area of the working partition is available. If the working partition has, say, 14.5GB free space, that's how much free space you will have in your container.

RW layer indirection:
To be entirely correct, the default behaviour is that the above diagram is not quite correct. Containers also have the same mechanism of mounting a zram device on the RW layer, so writes are written to RAM only. Exactly the same principle applies; when the session is saved, the RW layer is flushed to the containers .session folder.
And just like on the main filesystem, you can switch to direct writes to the .session folder; then the above diagram is correct.
This is all managed from the "save" on the main desktop; choose to save, and the RW layer will be flushed to the .session folder on the main filesystem as well as any running containers.

If you want to access files created in the container, staying with the example of SeaMonkey in a container, just look at /mnt/sdb2/easyos/containers/seamonkey/container (equivalent to /mnt/wkg/containers/seamonkey/container) -- do this while the container is running.

Or, as already mentioned, an app inside the container can save to /files/shared, and it will also appear at /files/shared in the main filesystem. This sharing mechanism is optional and can be turned off if considered to be a security issue.

Extra thoughts about file access in containers:
Yes, an app can export a file via /files/shared, but think about the above two paragraphs. On the main desktop, you can look at /mnt/wkg/containers/seamonkey/container and see everything inside. Thus, you can access any file inside the container. So for example if SeaMonkey downloaded to /files/downloads in the container, no problem, you can grab it.
Looking into a container from the outside, you are like God looking down from the Heavens.

There are security options, that will impose further restrictions on what can be done, with a view to keeping someone with ill-intent from somehow accessing outside the container. This is neat, but there is a downside. Some apps might not work, or not properly, especially as more of the security options are turned on.

SFSget

Reading the above might tend to cloud the understanding. EasyOS is best "just used", that is, use it and you will find it is easy. It becomes complicated when there is an attempt to explain everything that goes on "under the hood".

Yes, the Easy Container Manager, snapshot above, can turn any app into a containerised app. Great.

There is also an online repository of SFS files, and these can be downloaded and run in containers. These SFS files can be individual apps or complete distributions.

The dunfell container (or kirkstone container in the lastest series), described above, is an example of a complete EasyOS running in a container, as a separate window.

There is an icon on the desktop, labeled "sfs", click on that and you can access the online SFS repository. This link is an example, showing downloading of Xenialpup 7.5, a complete Puppy Linux distro:

http://bkhome.org/news/201811/xenialpup-75-running-in-easyos.html

So, yes, read these technical pages, but do go and actually do it, to appreciate the simplicity.

If you would like to learn more about the online SFS repository and even how you can create your own SFS repository that SFSget can access -- with a view to making it available to others -- please read this blog post:

https://bkhome.org/news/202003/sfsget-now-much-faster.html 

...you would also need to learn how the 'dir2sfs' utility works, see here:

https://easyos.org/dev/coding-for-easyos.html 

More technical usage highlights

it is planned to insert a few more introduction topics here. Or maybe a "part-3".   

Tags: tech

Distro


Translate EasyOS to your language

Originally posted January 12, 2020.
Updated: Feb. 9, 2020. June 11, 2023

It is quite easy to create a complete translation of EasyOS to any desired language. The tool used is MoManager, that was created for Puppy Linux in 2012, and is now used in various derivatives and forks of Puppy, including EasyOS. MoManager is a GUI application, written by Barry Kauler (BarryK in the Puppy Forum). A fork was maintained by Lutz Ulrich (L18L in the forum) and that one is used in the current Puppy Linux.

MoManager may be used to translate just one file, or many, and will generate a tarball of changes made in the current session (newtranslations-<language>-<date>.tar.gz) as well as a tarball of all translations (translations-<language>-<date>.tar.gz).

The usual sequence is the user would do some translations, exit with generated 'newtranslations-<language>-<date>.tar.gz' and then post the tarball to the forum here:

https://forum.puppylinux.com/viewtopic.php?t=8070

Barry will then download the tarball, check it and hopefully merge the translations into woofQ, the EasyOS build system. Note, woofQ is a project on github; however, currently Barry only accepts translations as tarballs via the forum.

The steps are pretty straightforward, and it is made even easier as MoManager can help with automatic translations. You will find MoManager in the "Utility" section of the menu. Choose it, and this is the first window:

img1

Choose "Automatic" and then you get the main window, for the example of French translating:

img2

The procedure is that you choose a file on the right-side and click the "Create" button. The great time-saver is that auto-translation will occur, and a file will open in Geany text editor, with entries like this:

#: easyshare.sh:37
msgid "Close"
msgstr "Fermer"

#: easyshare.sh:66
msgid "Scanned for remote shares, no change"
msgstr "Analyse des partages distants, aucune modification"

#: easyshare.sh:68
msgid "Scanned for remote printers, no change"
msgstr "Numérisation pour les imprimantes distantes, aucun changement"

#: easyshare.sh:88
msgid "The full 'hostname' utility is required, that supports the '-I' option."
msgstr "L’utilitaire 'hostname' complet est requis, qui prend en charge l’option '-I'."
#: easyshare.sh:169
msgid "You must click the <b>Network Connect</b> button, or <b>connect</b> icon on the desktop, to setup a connection to a local network."
msgstr "Vous devez cliquer sur le bouton Connexion réseau ou sur l’icône de connexion sur le bureau pour configurer une connexion à un réseau local."

You do need to check that the translations are sane. Also, notice the last translation of "<b>Network Connect</b>" -- the tags are missing in the fr translation. Some formatting, such as html tags, are removed before submitting to the Google or Bing translator, so as not to confuse them. But, this means you will have to put the tags back in -- well, in the case of "<b>...</b>" it isn't essential, as it just causes "Network Connect" to display as bold.

So, go through, checking that translations are correct, choose to Save, then Exit from Geany. Translate as many files as you want, then at the bottom of the window click on the "Click OK to exit and create translations tarball" button.

Then, you will find /root/newtranslations-<language>-<date>.tar.gz and also expanded as folder /root/newtranslations-<language>-<date> so that you can see what is in the tarball. These are all translations created or edited since power-on. An example is 'newtranslations-fr-20230611.tar.gz'.

There will also be accumulated translations to-date, for example 'translations-fr-20230611.tar.gz' as well as an expanded folder; however, Barry would prefer that you only post the newtranslations-* tarball to the forum.

The good thing is, you only have to translate as many files that you feel comfortable doing. One hour, two hours, whatever, create the tarball and post to the forum. The translations will accumulate, so every little bit helps.

EasyOS is currently supporting these languages:

bg:български cs:čeština da:dansk de:Deutsch el:Ελληνικά en:English es:Español et:eesti-keel fi:Suomalainen fr:Français hr:Hrvatski hu:mađarski is:íslenskur it:Italiano lt:lietuvių lv:latviski mk:македонски nl:Nederlands no:norsk pl:Polski pt:Português ro:Română ru:Русский sk:slovenský sl:slovenska sq:shqiptare sr:Српски sv:svenska tr:Türkçe uk:українська uz:Ózbekça

...so, if you are proficient in English and one of those languages, you are invited to contribute!

Language choice when booting Easy

At the very first bootup of Easy, you will be greeted with this window:

img3

...it is a text-mode interface, so press the down arrow to select your language, press the ENTER key, then at bootup the desktop will be in your language. For example, German:

img3

For the German build, you will see some English untranslated text here and there. If you want to fix those, you may use MoManager to do so.

The most-translated are currently French and German, followed by Russian and Spanish, then Turkish.

Now for some technical details. Some generic notes about translating various types of files...


Translating different types of files

There are different types of files that require translation. These can be roughly classified as two types: documentation files, and applications. Applications may be scripts or compiled executables. In EasyOS, compiled applications written by Puppy and EasyOS developers, are written in C or BaCon. Other applications may have been written in C++, Vala, etc.

A pre-compiled application will usually be provided with a ".pot" file. This file is what you use to create the translation, or rather, MoManager does. For example, look at /usr/share/doc/nls/audacious/audacious.pot -- this is the translation file for the Audacious music player.

BaCon is a BASIC compiler, that some Puppy/EasyOS developers use, due to it's relative simplicity compared with C or C++, in particular the ease of creating GUIs. So, some notes on translation of BaCon programs...

Applications written in BaCon

BaCon is a BASIC compiler. For a developer writing an application in BaCon, you will need to know how to compile it so that it produces both the binary executable and the .pot file. Internationalization is supported by the compiler, as explained here:

https://bkhome.org/archive/bacon/international.htm

The .bac file is the BaCon source code. The .pot file is the language translation file. When you compile a BaCon application, place the .pot file into /usr/share/doc/nls/<app>/<app>.pot. MoManager searches this path for .pot files to be translated.

Actually, the same thing holds for any application, written in C, C++, Vala, Genie, or whatever, place the .pot file at /usr/share/doc/nls/<domainname>/<domainname>.pot and MoManager will use it.

Applications written in C

There is a blog post:

https://bkhome.org/news/202010/how-to-internationalize-any-c-program.html

Scripts internationalized with 'gettext'

The vast majority of utilities and applications developed by EasyOS developers are shell scripts, written in Bash/Ash. See the 'Coding for EasyOS' page:

https://easyos.org/dev/coding-for-easyos.html

Incorporating internationalization support in shell scripts is easy...

There are a lot of scripts in EasyOS that use 'gettext' for translating. Here are some in /usr/sbin:

bootmanager
connectwizard
quicksetup
qwallpaper

Inside each script you will find a line like this:

export TEXTDOMAIN=myapp

MoManager finds all scripts with this entry, which confirms that it uses 'gettext', and offers a GUI interface for translating each script. You do not have to learn the commandline tools for translating, the GUI interface makes it easy.

Basically, MoManager will create a .pot file for the application, in the above example that will be 'myapp.pot'. Note that multiple scripts can have the same domainname 'myapp' and just the one 'myapp.pot' will be created. So, if your application has several scripts, you don't have to have a .pot for each (but you can if you want), just have the one .pot -- this is more efficient if there are common text strings to be translated in the scripts, and is simpler just to have the one .pot file.

One technical detail: please place the "export ..." at column one, and do not place quotes around "myapp", the line in the script should look just like shown above.

.pot files are "translation files", which you then have to insert the translations for a particular language. When that is done, it becomes a .po file, and it is then compiled to a binary form and becomes a .mo file. The compiled .mo files are kept at /usr/share/locale. MoManager handles these conversions for you.

MoManager and scripts

In the case of updating an existing translation file, MoManager automatically synchronises with the latest script, and will identify any changed strings -- if you see the text "fuzzy" anywhere in the translation file, it is likely that the original English text has changed and you will need to update the translation.

Although it is fairly easy to figure out how to edit a translation file, known as a 'po' file in it's editable form, or 'mo' file in it's compiled form, it is helpful to readup a bit on the topic. Suggested links:

http://docs.translatehouse.org/projects/localization-guide/en/latest/guide/project/howto.html

https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html#PO-Files

...note though, reading all of that can be confusing! It is possible to use MoManager without understanding all of those details.

MoManager uses a normal text editor to edit .po files rather than a specialized po-editor (such as poedit) and this is quite easy to do, you just need a very basic understanding of the format of .po files.

Have fun!  

Tags: dev

Distro


Guidelines for debugging EasyOS

Created: August 12, 2020
Updated: June 14, 2023; June 15, 2023

Making a start on writing this page...

EasyOS boots up from a boot-manager, such as Limine, rEFInd or GRUB, which loads the Linux kernel, file 'vmlinuz', and the tiny complete Linux OS into RAM, file 'initrd'. The 'init' script inside 'initrd' is then run, which does a lot of setting-up, especially creating the aufs layered filesystem, consisting of a read-write folder on top and file 'easy.sfs' on the bottom. There is then a switch_root onto the aufs layers, and hence to the desktop.

The 'initrd' is actually a "initramfs", and the latter is the word you will most likely come across if searching online for help about how it works. It really is a complete tiny Linux OS, commandline only. If anything goes wrong at bootup, or if you want to modify bootup behaviour, you will want to get inside the 'initrd'.

Opening up and editing the 'initrd'

You download EasyOS as a drive-image file, named "easy-<version>[-<language>]-<architecture>.img", for example "easy-5.4.1-amd64.img". This will be written to a drive, most often a USB-stick. In Easy, we have a nice utility to handle this, "easydd", or you could use the "dd" utility. In the target drive, you will find two partitions, a "boot partition" and a "working partition".

The boot-partition has the Limine boot-loader, that can boot on either UEFI-firmware or traditional BIOS computers. Here is a snapshot of the boot-partition, USB-stick, in this case it is /dev/sdc:

img1

...the 'EFI' folder contains files that Limine needs for UEFI booting.

The working-partition contains the installation of EasyOS, which initially is just three files 'vmlinuz', 'initrd' and 'easy.sfs':

img2

...notice the folder 'easyos'. That is an arbitrary name, it could be any name, or the installation could be deeper, for example 'easyos/kirkstone'.

Opening up and editing the contents of 'initrd' is simplicity itself -- just click on it. You can find some more details here:

https://easyos.org/tech/how-easy-works.html

You can, for example, edit the 'init' script. Having made changes, just click on 'initrd' again and it will be updated.

Debugging the 'initrd' at bootup

Perchance the 'initrd' doesn't do what you want, it is possible to dropout to a shell in the initramfs and poke around. If you examine the 'init' script, you will see that it recognises a kernel boot parameter of the format "qfix=<param1>[,<param2>...]", for example "qfix=nox" (which means bootup to commandline, without X. Note that you can have multiple, comma-separated parameters. At the time of writing, these are the recognised parameters:

lock1
Copy session to RAM & unmount all partitions
lock2
Copy session to RAM & disable drives
normal
Remove permanent lockdown, normal bootup
nox
Bootup to commandline, no X
fsck
Filesystem check of working-partition
back
Rollback to last snapshot
new
Rollback to pristine first-bootup
dropout0
Initrd shell: nothing yet mounted
dropout1
Initrd shell: boot & wkg partitions mounted
dropout2
Initrd shell: before recovery & maintenance operations
dropout3
Initrd shell: before version control
dropout4
Initrd shell: before setting up SFS layers
dropout5
Initrd shell: before moving mount points to layered f.s.
dropout6
Initrd shell: just before switch_root

Any of the parameters can be implemented by editing the kernel commandline in the 'limine.cfg' file in the boot-partition.

However, they can also be achieved via two other ways: a menu in the initrd, or the Shutdown menu. The latter assumes you have a working desktop of course:

img3

...the last bottom-two entries have further windows. The "Reboot to initrd" entry will bring up this window:

img4

...so, can achieve the same dropout to a shell in the initrd, as can be done by kernel commandline.

The way that these reboot options are created by the menu, is files are created in the working-partition that are read by the 'init' script in the initrd at next booup. For example, if you had chosen "Reboot to initrd (developers only)" from the Shutdown menu, a file '.debug.flg' gets created.

Dropout to a shell in the 'initrd' is extremely useful for debugging the 'initrd' at bootup.

A file .debug.flg will be created, with a parameter between "dropout1" and "dropout6" in it. The "Reboot later" button may be useful, as you could choose some other reboot option from the menu, such as "Reboot with rollback", and you will then be able to dropout to a shell in the initramfs to debug that mode of bootup.

If perchance X is not running, you can manually create .debug.flg, then reboot.

if the 'init' script hits an error, such that it is unable to continue bootup, it will also dropout to a shell in the initramfs. So, how to poke around inside the initramfs and attempt some debugging?

Debugging aids in the initramfs

the 'initrd' is based on Busybox, plus there are some other utilities, all statically linked. if you type "busybox<ENTER>" in the initramfs shell, you will see the list of applets available from busybox. Other utilities are, in /bin:
argon2 capsh, dialog, e2fsck, e4crypt, fdisk, fscryptctl, gpg, idump, 
mke2fs, mksquashfs, mp, readlink, resize2fs, shfm, tune2fs, vercmp

These are binary executables, except for 'shfm' which is a shell script. 'shfm' is particularly interesting, as it is a console file manager, to make it easy to navigate around in the filesystem. Here is a snapshot of 'shfm', running in a terminal emulator on the desktop ('shfm' is also in the main filesystem, after switch-root):

img4

...very simple, probably more accurately described as a "file browser" than a file manager. Keyboard navigation by the arrow keys, "?" for help, "q" to quit, "!" to spawn a shell. Right-arrow or ENTER key on any text file will launch the 'mp' text editor.

Although Busybox has a simple 'vi' editor, 'mp' is way better, with drop-down menus. Here is a snapshot, in a terminal emulator on the desktop ('mp' is also available in the main filesystem):

img6

After having poked around in the initramfs, type "exit" to continue bootup, to the desktop.

Files created by the Shutdown menu

The choices in the Shutdown menu may create a file that the 'init' script will read at bootup. File '.debug.flg' has already been mentioned. They are all located in the working-partition, for example /mnt/sdc2/easyos. Here is a list of all of them:

File
Purpose
.debug.flg
Exit to shell in initramfs
.lockdown.flg
Copy session to RAM
.fsckme.flg
Filesystem check of working-partition
.rollback.flg
Rollback
.qsfs.flg
Recompress 'easy'sfs' with gz
.zramtl.flg
Top-level zram or direct write to drive

You can examine the 'init' script to see the expected content of these files.

Menu in initrd

There is also a menu in the initrd, with a small number of choices:

img5


Editing kernel commandline in boot-loader

It depends what boot-loader you have, but whatever, you need to append parameters for EasyOS. For example, the USB-stick has the Limine boot-loader, with file 'limine.cfg', with something like this in it:

VERBOSE=no
TIMEOUT=10
DEFAULT_ENTRY=1
INTERFACE_BRANDING=EasyOS Limine Boot Manager
INTERFACE_RESOLUTION=800x600

:EasyOS Kirkstone
COMMENT=EasyOS Kirkstone bootup
RESOLUTION=800x600
PROTOCOL=linux
KERNEL_PATH=boot://2/easyos/vmlinuz
MODULE_PATH=boot://2/easyos/initrd
KERNEL_CMDLINE=rw wkg_uuid=8666a128-0766-11ee-968f-287fcfeb4376 wkg_dir=easyos/

As documented earlier in this page, you can add "qfix=..." parameter, which in the above case would go onto the end of the "KERNEL_CMDLINE" parameter.

When installing EasyOS, or debugging an installation, you might need to change those "wkg_uuid" and "wkg_dir" parameters.

Both of those are essential to boot EasyOS. They tell the 'initrd' where the working-partition is and in what folder Easy is installed.

Note the trailing slash "wkg_dir=easyos/". That is not essential. "wkg_dir=easyos" would suffice.

"wkg_uuid" is the filesystem UUID, that you can obtain by running the 'blkid' utility, for example:

# blkid /dev/sdc2
/dev/sdc2: LABEL="easy2" UUID="8666a128-0766-11ee-968f-287fcfeb4376" BLOCK_SIZE="4096" TYPE="ext4" PARTUUID="89263718-02"

What is very useful to know, is that there are two alternatives to "wkg_uuid":

wkg_uuid=8666a128-0766-11ee-968f-287fcfeb4376
wkg_dev=sdc2
wkg_label=easy2

You can use any one of those. However, there is a trap: "wkg_uuid" and "wkg_label" must be unique. Usually, the UUID is unique, but there are situations where there might be two partitions with the same UUID. Same with the partition label. So, whichever you use, be sure that it is unique.

"wkg_dev" is another trap. If booting from a USB device, the device name might change, so you cannot guarantee that it will always be "sdc2". Usually the names assigned to the internal drives will remain constant.

Here is a blog post with further clarification:

https://bkhome.org/news/202206/complete-separation-between-boot-manager-and-easyos.html

 

Tags: dev

Distro


How to install EasyOS on a new SSD

Page originally written March 13, 2019
Completely rewritten June 29, 2022, for EasyOS version 4.2.2 or later
Updated: July 2, 2022; December 31, 2022; June 16, 2023
Updated: June 28, 2023

This page describes how to install EasyOS on an entire drive, completely replacing what was on it before. This can be any drive; SSD or magnetic-platter HDD, internal or external. Also USB flash-sticks or SD-cards.

The original case study was install to a SSD in a Mele PCG35 Apo mini-PC, but these instructions apply to any computer with x86_64 CPU. Any amount of RAM, from 2GB upwards, and a video card with at least 800x600 pixels resolution (1024x768 minimum is better). And, as stated above, any drive, not just an SSD.

Also, any age PC, from very recent, right back to PCs with early x86 64-bit CPUs (earliest supported is the "nocona" CPU). If it has the ISA or EISA card interface, not PCI or PCIe, then it is too old.

It needs to be stated up-front, that installing EasyOS onto an entire drive is an extremely simple operation. Basically, you download the latest release, write it to the drive, then set the BIOS-Setup or UEFI-Setup to boot from the drive. There may be some extra details that you will need to consider, but that is the essence of it, "easy peasy".

The original case study

Back in 2019, the author of this page (Barry Kauler), bought a 240GB 2.5inch SATA Kingston SSD, and installed it in the Mele. An easy operation. Snapshot:

image1

The Mele has Windows 10. Which raises the question, how to download the latest EasyOS and write it to the Kingston SSD? While running Windows? Or bootup EasyOS or some other Linux from a USB-stick?

Either will be OK.

Download and write EasyOS to a drive

The current release of EasyOS (at the time of writing) is the Kirkstone-series. Download the latest from here:

https://distro.ibiblio.org/easyos/amd64/releases/kirkstone/

Let's say that it is 'easy-5.4.1-amd64.img'. You will also see an 'md5sum.txt' file, grab that too. It is important to verify the download file has not been corrupted. In Linux, you can do this:

# md5sum easy-5.4.1-amd64.img

...that will return a checksum, that you can compare with what is in 'md5sum.txt'.

If you are running Windows, there is an 'md5sum.exe', available from various sites, for example, here:

http://www.pc-tools.net/win32/md5sums/

To write the file to the drive, in Linux you will need to know its drive name, and be sure that it isn't mounted. Let's say that you identify the drive as /dev/sdc, do this as the root user:

# dd if=easy-5.4.1-amd64.img of=/dev/sdc bs=1M
# sync

...don't forget that "sync" to flush everything to the drive. And, be absolutely sure that /dev/sdc is the correct drive. /dev/sda is most likely your primary drive, and you definitely don't want to over-write that!

Another point for newbies, is write to the entire drive, in this example /dev/sdc, not to a partition, which will have a number, like /dev/sdc1

Any extra note: if you bootup EasyOS on a flash-stick, you will have available "EasyDD", which is a frontend for 'dd' -- it is in the "Setup" category of the menu. Read more about EasyDD here:

https://easyos.org/install/how-to-write-easyos-to-a-flash-drive.html#EasyDD_frontend_for_dd

...that page has a download link for EasyDD and it can be run on any Linux distribution, not just EasyOS.

If running Windows, you will need to install an app that writes an image file to a drive. This is not a CD/DVD burner app! -- though some apps might do both. Here are a few of them:

Win32 Disk Imager
https://win32diskimager.org/
USB Image Tool
https://www.alexpage.de/usb-image-tool/
Etcher
https://www.balena.io/etcher/
DMG Editor
https://www.uubyte.com/dmg-editor.html

EDIT June 28, 2023:
We are no longer recommending Balena Etcher. Reasons given here.
 

The Author has only personally used "USB Image Tool". "Etcher" used to be recommended by the Raspberry Pi people, but in recent documentation they are recommending "DMG Editor". USB Image Tool usage is described here:

https://easyos.org/install/how-to-write-easyos-to-a-flash-drive.html#USB_Image_Tool

In Windows, if writing to an external drive, you will find in the tray an option to flush all buffers to the drive, to make it safe to remove.

That's it EasyOS is installed. In the drive, you will find two partitions, a 7MiB fat12, and a 816MiB ext4 partition. The former has the Limine bootloader, so that is the boot-partition and will handle booting on either legacy-BIOS or UEFI computers. The ext4 partition will get expanded to fill the drive at first bootup -- so you can have any size drive, up to 2TB.

The only remaining task is to get your computer to boot from the new drive...

Precaution

Before explaining how to boot the new drive, a digression. This section is added as someone hit this problem, and became very confused.

As stated above, there are two partitions, a vfat boot-partition and ext4 working-partition. The former contains the Limine boot-loader and the latter is where EasyOS is installed.

The boot-partition contains file 'limine.cfg', which contains text, including a line like this:

KERNEL_CMDLINE=rw wkg_uuid=1ca8506e-79f5-11ed-b964-287fcfeb4376 wkg_dir=easyos/

This tells the Linux kernel what partition and the folder where EasyOS is installed.

What the person had done was boot EasyOS from a USB-stick, then dd the image-file to the internal drive. The exact same version as booted on the USB-stick. He then tried to boot the installed EasyOS, while leaving the USB-stick plugged in.

This caused the Limine boot-loader to be confused, as it saw two partitions with the same UUID, and bootup failed.

If you are new to all of this, don't worry about the technical details. Just recognize the problem that has occurred, and the simple fix...

Solution: power-off, remove the USB-stick, then bootup Easy on the internal drive.

So the precaution is, avoid a situation where there are two partitions with the same filesystem UUID. Also good to avoid partitions with the same filesystem label.

A further digression, without wanting to add too much verbiage to this page; if you are running a Linux distribution, you can see the UUID and label of any partition, and change if desired. For example, say that the working-partition of the internal drive is sdb2:

# blkid /dev/sdb2
/dev/sdb2: LABEL="easy2" UUID="1ca8506e-79f5-11ed-b964-287fcfeb4376" BLOCK_SIZE="4096" TYPE="ext4" PARTUUID="35e141c5-02"

This will change the UUID to a random value:

# tune2fs -U time /dev/sdb2

...and you will then have to edit 'limine.cfg' with the new UUID value. Anyway, this is very much a "corner case".

Just one extra note: there are two alternatives to "wkg_uuid" on the kernel commandline; "wkg_dev" or "wkg_label". These are explained on this page:

https://easyos.org/dev/guidelines-for-debugging-easyos.html

Back onto booting Easy...

Configure to bootup EasyOS

There are a lot of decisions to be made here, depending on your situation. That's a rather vague statement, but what it boils down to, is you have to tell the BIOS-Setup or UEFI-Setup to boot EasyOS, or make an entry in an existing boot manager, such as GRUB, to boot EasyOS, or install a boot manager.

The above paragraph might seem complicated, but for the case study of this page, we already have a boot-loader installed; Limine. The only thing remaining is to configure the BIOS-setup or UEFI-Setup to boot it.

Which is pretty easy to do. Before explaining that though, another digression...

The page linked here has extra very useful information. Especially please read it if the computer has Windows installed:

https://easyos.org/install/prepare-your-computer-for-booting-linux.html

...it explains certain precautions need to be taken to ensure Windows does not become corrupted in a dual-booting setup.

Anyway, the very simple procedure to get the computer to bootup EasyOS...

You can configure the BIOS-Setup or UEFI-Setup to boot EasyOS. You need to know the hot-key that you hold down after power-on of the computer, usually "DEL", "ESC", or "F12", and you will find a text-mode interface where you can choose to boot EasyOS.

Note, most PCs have two different hot-keys. One of them brings up a boot-menu, the other brings up the BIOS-Setup or UEFI-Setup. The boot-menu is a once-only choice, it doesn't alter the BIOS/UEFI firmware flash memory. That's OK for a quick test, but if you want to make the new boot-choice permanent then you will need to go into the BIOS/UEFI Setup.

In the case of the Mele the hot-key is the "ESC" key, and the UEFI-Setup will open:

image8

...notice, the "SanDisk Extreme" drive is at the top. That is a USB-stick, that the Author booted EasyOS from in the original case-study. The Kingston SSD is down at #5, and it has to be moved up to #1. Note, #3, "[UEFI OS]", is a fat32 esp partition that the Author created for earlier installation experiments -- just ignore that.

So, you choose the Kingston SSD, and off you go, the Limine menu will display for several seconds, then EasyOS will startup and you have a desktop:

img9

You can leave EasyOS as the default choice in the BIOS-Setup or UEFI-Setup; however, there is something interesting to think about...

In the new drive, the Kingston SSD in the original case study, you will see two partitions; as already mentioned, 7MiB fat12 boot-partition and a second ext4 partition that has the installation of EasyOS.

That boot-partition has the Limine bootloader, and it has a menu, file 'limine.cfg', to which you can add more entries. You could make entries for other operating systems installed on the computer, including Windows.

Barry has posted how to add Windows 10 to the Limine menu, at his blog:

https://bkhome.org/news/202207/how-to-add-windows-to-the-limine-boot-menu.html

So, from the Limine menu, you could choose to boot a different OS, if the fancy takes you.

Note also, EasyOS has "Limine Installer", in the "Setup" menu, that can be used to discover all of the installed OSs and automatically create a 'limine.cfg'. You could use this to add extra OSs to the existing 'limine.cfg' file.

Conclusions

You should find the steps described on this page to be pretty straightforward, fun, and, we expect, very rewarding.

Of course, writing an image to a drive is something that you must take responsibility for. If you accidentally overwrite the main drive, that is your fault! These instructions are given with that understanding.

One very good thing about the method described above, of going into the BIOS-Setup or UEFI-Setup and choosing the new drive, is that it does not alter the main drive at all. You could simply remove the new drive, and go back to how everything was before.

Anyway, enjoy!

Oh, and do be sure to monitor Barry's Blog, to find out about new developments and releases:

https://bkhome.org/news      

Tags: install

Distro


Package manager concepts

Page created: April 3, 2023
Updated: April 8, 2023. June 11, 2023. August 5, 2023

This page is an overview of packages and package managers; what are the choices, how do the packages install, how do you use them, how to remove.

To install or remove a package, click the "pkg" icon on the desktop:

img8

This brings up a window offering a choice:

img9

...yes, EasyOS has not just one package manager; Easy has four different package managers:

PKGget

This is the traditional package manager. Packages are tarballs, of various formats, such as .pet, .tar.xz, .deb, .rpm. These install directly at "/" in the main-filesystem.

SFSget

These are large apps, or many apps, in a read-only file, that is mounted as a layer in the layered filesystem, either in the main-filesystem or in a container.

Appi

These are also large apps, in a read-only file. They are intended to be Linux-distribution-independent, with all dependencies builtin. They run in the main-filesystem, but not installed like traditional packages.
Flapi
Flatpaks are also large Linux-distribution-independent applications, with all dependencies builtin. They also run in the main-filesystem, but not installed like traditional packages.

A key concept in EasyOS is that the "main-filesystem" is created by layers, like this:

/
this is the abstraction, view at the top
RW layer folder
this is the .session folder in the working-partition
RO layer folder
optional extra sfs file, for example devx.sfs
RO layer folder
easy.sfs is mounted on this folder

Containers are also built with layers, looking just like the above. Here is a visualization of how the four package managers install:

img1

...it is all very well seeing pretty diagrams, as they are supposed to make everything clearer. One thing that the above diagram doesn't really explain, is how the SFS, AppImage and Flatpaks are actually installed, compared with traditional packages.

So, another pretty diagram. This one shows where those three types of package get downloaded to:

img10

...so, they are actually installed into the working-partition, and menu-entries, symlinks, etc., created to make then available in the main-filesystem or, in the case of SFSs alternatively available in a container.

To find the app you want, you do need to become familiar with what is in all four package managers. The example is given of OBS Studio as an SFS file, but in EasyOS Kirkstone-series it is also in PKGget, the traditional package manager. In theory, OBS could also be provided as an AppImage or a Flatpak.

So, explore. If you have a choice, say OBS in PKGget or SFSget, it is helpful to have an appreciation of the advantages and disadvantages of each. Here are some notes, firstly concerning security:

Security

PKGget

These packages install directly at "/" in the main-filesystem. By default, the installed app will run as the 'root' user, so this is the least secure. However, it is possible afterward, to change to run as non-root user; see the menu "System -> Login & Security Manager".*

SFSget

These mount either as a layer in the main-filesystem, or in a container. In the former case, the app will run as the root user or non-root, depending on how the SFS was created. In the latter case, the app will run as "crippled root" and in some cases as user "spot".**

Appi

These all default to run as a non-root user in the main-filesystem.
Flapi
Flatpaks run as a non-root user in the main-filesystem. They have a builtin sandbox, so inherently more secure than AppImages.

             
*
Or, click on the "kirkstone" icon and the entire EasyOS will run in a container. This is very secure "crippled root" and PKGget will work in this environment.
Or, run EasyOS in a QEMU VM. Still running as root, but isolated.

**
The Author is creating most SFS apps to run non-root, except those that are best as the root user, such as the "devx" SFS

Here is part of the "Login & Security Manager" window, in the Author's currently-running system:

img2

...Chromium and hexchat are actually in easy.sfs. The others are AppImages or Flatpacks. Apps installed non-root run as separate unique users, for maximum isolation. Each app has its own home folder, as seen in the Author's recent system:

img3

...it is not just superior security; this isolation is also good from an organization viewpoint; the data of each app is completely separate from others.

So, security of an app running non-root on the main filesystem is excellent, approaching that of running in a container. So take your pick.

So what about ease of updating and removal? Here is a table from that perspective:

Updating & Removal

PKGget

The versions are fixed, until the repository is updated. PKGget is able to install and remove. In some cases, an app has its own update feature.

SFSget

These are also fixed versions. If the app has an update feature, that will work. SFS files are a single file, and very easy to uninstall, just by removing the file. However, it is recommended to uninstall via the menu "Filesystem -> Easy BootManager" so as to remove menu entry, etc.

Appi

As the AppImage file is just one file, uninstall is quite easy, just delete it; you will find it at /mnt/wkg/appimage. However, to get rid of the the menu entry and link from /usr/bin, the easiest way is to choose uninstall in Appi.
AppImages have serious problems with updating; if the app offers to update, decline, as it in a read-only file. Appi is able to probe for a latest version, though it is not guaranteed to work, see explanation here.
Flapi
Flatpaks support updating, that you can do via Flapi (the Flatpak Installer). Flapi can also uninstall.

Finally, thinking about general usage and usability:

General usage

PKGget

No real problems, except that most of them default to run as root, which some users object to (but see * above).
These have the highest level of compatibility with the host system, as they were compiled to link against all the exact same libraries as in the host.

SFSget

If install to the main filesystem, a reboot is required before can use it, due to it being a layer in the filesystem. In a container, is available immediately.
The disadvantage in a container is that the app may be noticeably slower to start and run.
Some SFS apps work on the main-filesystem, but not in a container, due to the more severe security restrictions.

Appi

These work well, start and run fast.
As they default to run as a non-root user, they can only open and save files in their home folder, or under /files
Flapi
A bit slow to startup. Downloads and updates are massive; you need a fast Internet connection with generous data allowance. The sandbox can be a pain if you need to circumvent it.

The above tables are generalizations. More details could be added, but then it becomes a trade-off; too much detail causing confusion. So, advice is to just use the four packages managers, explore.

Here are some links for further reading:

Further information

PKGget

SFSget

Appi

Flapi

As well as the overall conceptual "How Easy Works" pages:

Have fun!   

Tags: user

Distro


How and why EasyOS is different

EasyOS was born in January 2017, and since then there have been bits and pieces written here and there about how and why it is different from other Linux distributions. This includes some rather technical descriptions. What is needed is a simple plain-English list, so that anyone can get a quick idea of what EasyOS is all about.

So, here goes. Do note, though, that Easy is an experimental distribution, and the features may change, and some features are a work-in-progress. These items are not listed in any particular order...

Container-friendly
EasyOS is designed from scratch to support containers. Any app can run in a container, in fact an entire desktop can run in a container. Container management is by a simple GUI, no messing around on the commandline. The container mechanism is named Easy Containers, and is designed from scratch (Docker, LXC, etc are not used). Easy Containers are extremely efficient, with almost no overhead -- the base size of each container is only several KB.
Very fast
While using Easy, everything happens in RAM. App startup appears to be almost instantaneous, even very large apps such as LibreOffice startup in the blink of an eye. Ditto when starting a container, blink of an eye. Depends on your PC of course!
Flash drive will last "forever"
The default mode is to have a "save" icon on the desktop, to flush RAM to drive whenever you want, or not at all, or at shutdown. Thus, writes to the drive are severely constrained. See here and here.
Totally isolated from drives
The boot menu has an option "Copy session to RAM & disable drives", which boots to a desktop with power of administrator (root) in all respects except totally isolated from the drives of the PC. This is an alternative to using containers, and is intended to be even more secure than containers. An introduction is here.
Run as root
This is controversial, however, it is just a different philosophy. The human-user runs as administrator (root), apps may optionally run as a non-root user or in containers as "crippled root". The practical outcome is that you never have to type "sudo" or "su" to run anything, nor get hung up with file permissions.
Easy runs each non-root app as its own user. For example, by default Firefox runs as user 'firefox', and SeaMonkey as user 'seamonkey'. Installed AppImages and Flatpaks also default to run as their own user.
It is easy to do the same for any app, that is, run it as its own user, isolated from other users.
Top-level /files folder
/files is a symbolic-link to the same-named folder in the working-partition, and is a permanent place for all your personal files. The above-mentioned apps running non-root, all have save permission under /files. In fact, almost all apps default to open and save under /files. Explanation here.
Furthermore, each app has its own private folder under /files. For example, Kdenlive video editor AppImage or Flatpak has /files/apps/kdenlive, that no other app can see into.
No ISO!
ISO for optical media is a legacy format. Very few desktop PCs are sold these days, it is mostly laptops, and none of those have optical drives. Easy is provided as an image file that can be written to any Flash-stick of 4GB or greater (and will auto-grow to fill the drive). Or, the file can be opened up and directly installed to internal hard drive. Rationale here.
No full install
In a traditional "full" installation, the filesystem occupies an entire partition, with the usual /etc, /bin, /usr, /proc, /sys, /tmp, etc. Easy does not install like this.
Easy installs to hard drive in what we call frugal mode, which occupies just one folder in a partition, allowing to co-exist with whatever else the partition is used for.
Installation is so simple: Just copy three files 'vmlinuz', 'initrd' and 'easy.sfs' into a folder in any ext4 partition, and that's it, Easy is installed. All that remains is to create an entry in the boot manager.
Roll-back, roll-forward
With Easy, you can take a snapshot, and later on roll-back to it. Then, you can roll-forward. This can work across version changes, kernel changes. This mechanism applies to the main filesystem as well as the containers. The link below has more information.
Atomic version upgrade
Unlike distributions that perform version upgrade on an error-prone per-package basis, Easy is upgraded by replacing three files (listed above). Thus, successful upgrade is "guaranteed". This is analogous to "atomic transactions" in finance. Read more here.
Four package managers
Easy has four package managers: PKGget, SFSget, Appi and Flappi, to readily make available just about any package that you might want to use. The underlying concepts are explained here. Any one of these may be run via the "pkg" icon on the desktop. Brief points about each one follows:
SFS mega-packages
Easy supports Squashfs mega-packages via SFSget, which are lots of packages bundled into one file, which is named with ".sfs" extension. These never get extracted, when in use they are mounted in the aufs or overlayfs layered filesystem, and can be uninstalled just by removing. For example, there is devx_<version>_amd64.sfs, which has everything required for compiling and debugging. There is also kernel source SFS, and so on. SFSs make life very simple!
Package manager audit trail
PKGget is the traditional package manager, hailing from the Puppy Linux days. However, it does have some steroids pumped in, for example:
PKGget maintains an audit-trail. One outcome, if install a package that overwrites an existing file, the "deposed" files are kept (see /audit/deposed) and restored if the package is uninstalled. Read more here.
AppImages and Flatpaks
Appi and Flapi are package managers for AppImages and Flatpaks, but offer more than you might expect. An app will install such that it runs as its own user, isolated from other apps. Menu entry and desktop icon are created, updating is supported. See a snapshot of Flapi here. -- Appi has a similar UI.
Run anything in containers
SFS files and containers, combined, are very powerful. You can choose any app to run in a container. You can even run other Linux distributions (currently restricted to only Puppy-derivative distros). Container startup is typically around 1 second. For example, Puppy Linux Xenialpup 7.5.
pup_event service manager
Easy uses the Busybox 'init' system, no systemd! To provide management of services with dependencies, there is pup_event, a simple extension to the init-system. For example, a daemon could be brought up only when network is active. pup_event also provides an extremely flexible and simple IPC mechanism, pup_event_ipc.
sudo-sh replaces sudo
The 'sudo' binary is replaced by 'sudo-sh', a much simpler mechanism for non-root apps to run a program as the root user. See here and here.
What is not in Easy
No systemd, and it is also worth noting what else Easy does not have: policykit, pam, avahi. The Kirkstone-series does have pulseaudio, and "putting the toe in the water" experimenting with pipewire.
GUIs for everything
The objective is that everything in Easy be configured by simple GUIs, without having to fiddle about on the commandline. This includes management of SFS files, BootManager, VersionControl, EasyContainers, pup_event, BluePup, EasyShare., MSCW (Multiple Sound Card Wizard), EasyApps, EasySetup and EasyJWM.
Non-standard hierarchies
When someone boots up Easy, they will see that the menu (bottom-left of screen) is different from what they are accustomed to. Ditto the folder hierarchy. The thing is, keep an open mind -- it is very easy to adjust, and there are solid reasons for the differences.
JWM-ROX desktop
Everyone knows about Gnome, KDE, Mate, XFCE and LXDE desktops, very few are aware of JWM-ROX. This has been used by Puppy Linux since around 2004, and is an extremely lightweight (fast) yet powerful desktop. JWM is a window manager (and provides the system-tray and menus), and ROX is the ROX-Filer file-manager and desktop handler. They work extremely well together, and are the choice for Easy.
Icon-free desktop
Easy is able to flip between a traditional desktop with icons, and an icon-free desktop with all icons in the system-tray. Information here and here.
Note: you can flip via "MoveIcons tray or desktop" in the "Desktop" category of the menu.
Encryption
The "working-partition" has folders that may optionally be encrypted. These folders are everything, all your work, downloads, history. etc. Encryption is by fscrypt, uses AES-256-XTS, and requires that a password must be entered at bootup.
Note: the /files folder, where you would keep all your projects, for example Kdenlive video editor projects, is also encrypted (/files is a symlink to same-named folder in the working-partition).
x86_64 and aarch64
In theory, as Easy is built from woofQ, it can use any binary packages, i686 for example. However, each architecture requires time and effort to support, so Easy releases are only x86_64 and aarch64 builds. In the latter case, have targeted RPi3&4 boards.
Network interfaces not renamed
Easy keeps the kernel-assigned interface names, eth0, wlan0, etc., does not rename them to something weird such as "enp2s0", as do most distributions. Easy network management has no problem with keeping track of the correct interface, even if the kernel-assigned names change.
Drive names not renamed
Ditto. The kernel-assigned names for drives and partitions are retained. For example drive sda and partition sda1.
Also, unlike other distributions, all partitions are mounted under /mnt, with folder-name the same as the partition, for example, /mnt/sda1
Hardware profiling
Boot EasyOS from a USB-stick on different computers, and automatically remembers the setup for that hardware. A work-in-progress, but coming along very nicely. modules temperature video alsa pulseaudio clock  
Compiled from source
Easy is built with woofQ, which takes as input binary packages. These packages can come from any distribution, such as Ubuntu DEBs; however, to reduce bloat and undesired architectural features, the current release of EasyOS uses binary packages created by a fork of OpenEmbedded with "meta-quirky" layer (overview here and github project here). That is, all packages in Easy are compiled from source, there is no reliance on any other distro. This does mean a much smaller repository; however, they are optimized for Easy (small and fast). It is currently almost 2,000 packages.
Note: PKGget, the traditional package manager, can install from this repository.
Puppy heritage
Barry Kauler created Puppy Linux in 2003, turned it over to the "Puppy community" in 2013. It is only natural that a lot of "puppyisms" can be found in Easy; though, it must be stated that Easy is also very different, and should not be thought of as a fork of Puppy. Inherited features include the JWM-ROX desktop, menu-hierarchy, run-as-root (with optional non-root apps), SFS layered filesystem, PET packages, and dozens of apps developed for Puppy.
"Everything but the kitchen sink"
Easy continues the Puppy tradition of including a large suite of applications, to cater for the needs of most users, yet keeping the download small. Easy takes it to the next level, aiming to have "everything" built-in, to satisfy "99%" of users, yet keep the download size around 800MB. Example built-in package-list here.
Support
for old computers

Easy runs on modern UEFI-firmware computers, but is also dedicated to supporting old BIOS computers.
The minimum requirement is that it must have a x86 64-bit CPU, going right back to the "nocona" CPU which is the earliest released by Intel and also compatible with early AMD 64-bit CPUs. The computer must have at least 2GB RAM (and drive with swap-partition when only 2GB RAM) and a PCI or PCIe bus (not ISA or EISA), and the monitor at least 800x600 (1024x768 is the preferred minimum).


As stated, EasyOS is an experimental distribution, and is continually evolving. To follow progress, monitor Barry's blog:

https://bkhome.org/news/tag_easy.html

It is hoped that these highlights will give a positive appreciation of what EasyOS is all about!  

Tags: about

Distro


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

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

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

Distro


Why the ISO format has to die

Page originally created December 28, 2021
Updated: November 14, 2022

EasyOS ships as a .img file, that is written to a drive. Barry stopped shipping EasyOS as an ISO file from early 2020. This was a controversial decision. Barry will continue the rest of this page writing in the first-person.

When I first wrote this page, in December 2021, I was reacting to emails that I had received. Quite incredible emails; one guy told me it is not my fault, I am showing the signs of early dementia!

My reaction below, is somewhat confronting, but it represents my mood at the time. Revising this page in November 2022, I decided to leave that text as-is...


I maintain that the ISO format has "had it's day" and needs to be retired. Furthermore, I claim that the image format is simpler and easier to use; however, some Linux "old timers" claim the opposite.

I saw their entrenched obstinacy as akin to my elderly step-mother sticking with audio cassettes and keyboard flip phone. So finally, in December 2021, I decided to clarify my claim in a blog post:

https://bkhome.org/news/202112/why-iso-was-retired.html

I also started a thread on the Puppy Forum for feedback, and as a consequence wrote a follow-up blog post:

https://bkhome.org/news/202112/why-iso-was-retired-part-2.html

If anyone reading this feels that they would like to contribute an opinion, here is the forum thread:

http://forum.puppylinux.com/viewtopic.php?t=4690

However, please do not just post your pre-conceived prejudices and narrow understanding.

Misunderstandings are OK, as long as the person is willing to learn.

For example, someone sent me an email yesterday (December 26, 2021) asking if they needed to format the usb stick with an ext3 or ext4 partition before writing the 'easy-3.1.17-amd64.img.gz' (latest release at time of writing) file to the drive. I replied that it doesn't matter what is on the drive beforehand, just use Etcher or easydd or some other tool that will write the image file to the usb-stick, then boot from the stick and you are good-to-go.

A note to anyone reading this, who needs help on how to use tools like Etcher or easydd, see this page:
https://easyos.org/install/how-to-write-easyos-to-a-flash-drive.html

That person was willing to learn and did follow my instructions. Unlike the entrenched "pro ISO" elderly Linux users, who just "dig their heels in" and re-state their fossilized opinions.

I will make one more statement. I received an email recently, the person stated that they understood ISOs and just didn't want to have to learn something different. This attitude is common among the elderly Linux users. The funny thing is, there isn't much to learn to make the switch to image format. The one area of difficulty is opening up an image file if one wants to extract the contents (vmlinuz, initrd, easy.sfs); however, that difficulty only applies to legacy Linux distributions, not to EasyOS.


Fast forward to November 2022, editing this page, I will add a more fundamental reason why I don't want to release EasyOS on an ISO anymore: it undermines what Easy is all about.

What I mean by that, is all of the documentation about Easy, and the features of Easy, are based on the layout of a boot-partition and a working-partition, whether it be in a USB-stick or installed in internal partitions.

If there was a live-CD, I would have to put in conditions throughout the documentation, like "except that you cannot do that if booted from a live-CD". The behaviour having booted from a live-CD is very different, and it adds up to a maintenance overhead, meaning it takes up my time.

There are only so many hours in the day. I have a tendency to get enthusiatic about something new, then get burnt out and have to wind back. Easy is, essentially, a one-person project, and I have to remain focussed on what is really needed.      

Tags: about

Distro