Clone this wiki locally
This page will explain how development of VaporOS is done. The most important thing to know is that this project works by downloading the latest SteamOS ISO, extracting it and putting it back together with the VaporOS packages added to it.
Join our Discord if you have any questions after reading this page.
Here is a list of files and directories in this project and what they do.
Within the root of this repo there are 3 script files:
After cloning this repo, the first out of these scripts which will be run is the add-packages.sh script. This script downloads all packages needed for the project. It gets these from the default.preseed and base_include files in the additions directory and a variable in the script. It creates a packages directory to put the packages in. It uses sudo to create a chroot to be able to download all dependencies
Out of these, gen.sh is the most important one. It builds the complete ISO. It used packages from the packages directory to do so! It transfers the content of the additions directory to the ISO it builds, overwriting files, more on that later.
The create-chroot.sh can be used for testing if all the packages in the .disk/base_include file install correctly. It creates a chroot environment from the buildroot directory of the ISO which was last generated. This fails if one of the packages from the .disk/base_include file fails to install. The chroot this script generates can also be used for other purposes. The add-packages.sh script also uses this script as well for creating the chroot it uses to download packages with.
The content of the additions directory will be copied on the ISO which gen.sh builds. It contains the bootloader configuration for the ISO and the following configuration files:
- .disk/base_include (press ctrl+h in nautilus to be able to see this directory)
The default.preseed facilitates the automated installation. It also adds some packages to the system in the pkgsel line (just search for that in the file).
The base_include file contains a list of packages which will be installed in the first step of the installation process. This step is really bad at dependency resolution, so a lot of packages are installed later by the default.preseed file. Testing if the packages in this file install correctly can be done with the create-chroot.sh script.
The firmware.txt file contains which firmware files should be loaded when the ISO is booted.
The vaporos-archive-keyring.gpg file contains the public key of the VaporOS repository. Chroots created with create-chroot.sh have access to it.
The deb-multimedia-keyring.gpg file contains the public key of the Deb Multimedia repository. Chroots created with create-chroot.sh have access to it.
The isohdpfx.bin file is used for generating the iso. You need it, otherwise the ISO might not boot.
Here is a list of packages which have been specifically created for VaporOS (which may be outdated at this point):
- vaporos-repo: This package adds the VaporOS repository by adding vaporos.list to /etc/apt/sources.list.d/
- vaporos-archive-keyring: This package adds the public key for the VaporOS repository to the system. Without it package installation will fail, which is why vaporos-repo depends on this package
- vaporos-autoupdate: Makes the SteamOS autoupdater also update packages from the VaporOS repository
- vaporos-ftpserver: An FTP server with a simple interface which shows instructions on screen on how to reach it. It generates a random password each time it is launched and only allows access to the home directory of the current user. The source code for it can be found here on Github
- vaporos-packages: This package doesn't contain anything, but it does have all VaporOS specific packages listed as dependencies. This allows us to add new packages to VaporOS later without forcing users to reinstall or tinker with the command line to get the new packages. It also makes it possible for SteamOS users to upgrade their system to VaporOS easily.
All retroarch/libretro packages were packaged for the SteamOS tools repo, which is no longer up. Some of the documentation for it can be found here.
The kodi packages come from the deb-multimedia repo.
Both kodi and retroarch have been added as dependencies to the vaporos-packages package.
Adding a new package can be a bit strange. In essence, it is very simple, you add your package to the packages directory and add its name to either the pkgsel line in the
default.preseed file or the .disk/base_include file, depending on the type of package. Run the
gen.sh script and you have an ISO with your package.
Packages in the packages directory should not be added to git, though. The
add-packages.sh script will fail if there are any packages in the
.disk/base_include file which are not found in a repo know in the chroot (Look at the finishchroot function in the
create-chroot.sh script). So if you'd like to add a package to VaporOS, you'd either need to setup a repository (use reprepro for this if you're doing it, it is the easiest way) or get your package in the VaporOS repository. To do the latter, make a pull request to the VaporOS repository git repo here.
This is the guide to use. There is barely any other documentation for reprepro unfortunately. Updating this section of this page is on my todo list. Ask in Discord if you need help with setting up the web server or anything else.
After having done that, add your public key to the vaporos directory and change the finishchroot function in the
The scripts in this repo can be used rebuild ISOs of any Debian based distribution with relatively few modifications. Come in Discord and ask Wouter for help if this is what you want to do. The gist of it is that you'll need to change some variables at the top of the 3 main scripts and replace the additions/.disk/base_include file with the one from the base ISO you're using. The default.preseed should be removed or replaced, depending on what you want to do with it. Any other file on the ISO can be replaced by adding the alternative to the additions directory.
It is likely that the bootloader configuration will need to be changed for your system, copy the bootloader directory from the base ISO into the additions directory and change it there.