Revision as of 01:08, 27 June 2015

This is a detailed tutorial aimed at beginners how to build Manjaro ISOs.

Manjaro Openbox edition is used as example throughout this tutorial, but there are many more pre-made Manjaro ISO profiles available: cinnamon, enlightenment, gnome, i3, kde, kde5, lxde, lxqt, lxqt-openrc, mate, net, net-minimal, netbook, net-openrc, openbox, openbox-legacy, pantheon, pekwm-openrc, xfce, xfce-minimal, and xfce-openbox-openrc.

Prerequisites

manjaro-tools-iso-profiles is needed for pre-built Manjaro ISO profiles.

buildiso is needed to build an image/ISO from these profiles. Before March 2015, it used to be part of the manjaroiso package, but now it is integrated into manjaro-tools-iso.

Please make sure you always use the absolute latest manjaro-tools-iso and manjaro-tools-iso-profiles packages available in order to minimize the chance of random or unexplained bugs.

Install manjaro-tools-iso

buildiso has often bugs introduced my new upstream package changes, therefore it is recommended to install the absolute latest version with the most recent bug fixes. A relatively easy way is to install manjaro-tools-iso from the unstable repositories of Manjaro:

If you are using the unstable repositories already:

sudo pacman -S manjaro-tools-iso

If you do not use the unstable repositories, you need to install manjaro-tools-base and manjaro-tools-iso from the unstable repositories manually:

Please keep in mind that you need to update/re-install these packages every time a new version gets released.

Go to this Manjaro mirror in your web browser:

http://mirror.netzspielplatz.de/manjaro/packages/unstable/extra/

Choose your architecture and search for the manjaro-tools-base and manjaro-tools-iso packages and remember their complete names (especially the version number).

Then, use your architecture and the name to install manjaro-tools-base and manjaro-tools-iso directly, e.g. with these commands:

sudo pacman -U http://mirror.netzspielplatz.de/manjaro/packages/unstable/extra/x86_64/manjaro-tools-base-0.9.8-3-any.pkg.tar.xz

sudo pacman -U http://mirror.netzspielplatz.de/manjaro/packages/unstable/extra/x86_64/manjaro-tools-iso-0.9.8-3-any.pkg.tar.xz

Alternatively, you can download and build the complete manjaro-tools from GitHub directly. In this case, you should build the absolute latest available manjaro-tools from the devel branch. This branch is in sync with the devel branch of manjaro-tools-iso-profiles.

Install manjaro-tools-iso-profiles

Clone manjaro-tools-iso-profiles profiles from GitHub (this requires the git package to be installed on your system). Open your terminal in your home directory (or any other directory you want) and type:

git clone https://github.com/manjaro/manjaro-tools-iso-profiles.git

Update manjaro-tools-iso-profiles

Whenever you want to update the manjaro-tools-iso-profiles directory with the latest files from GitHub, execute these commands:

cd manjaro-tools-iso-profiles

git pull origin master

ISO profile

ISO profile overview

Your manjaro-tools-iso-profiles folder contains these ISO profiles:

cinnamon/
enlightenment/
gnome/
i3/
kde/
kde5/
kde-minimal/
kde-openrc/ 
lxde/ 
lxqt/
lxqt-openrc/
mate/
net/
netbook/
net-minimal/
net-openrc/
openbox/
pantheon/
shared/
sysmenu/
xfce/
xfce-minimal/
xfce-openrc/
README.md

The shared ISO profile is special, because it contains common files for all Manjaro ISO profiles (unless the profile creators explicitly used their own customized files)

Let's take a closer look at the XFCE profile folder (marked above):

xfce-overlay
isolinux -> ../shared/isolinux/
mkinitcpio.conf -> ../shared/mkinitcpio.conf
overlay -> ../shared/overlay/
overlay-livecd -> ../shared/overlay-livecd/
Packages -> ../shared/Packages-Systemd
Packages-Livecd -> ../shared/Packages-Livecd-Systemd
Packages-Xfce
Packages-Xorg -> ../shared/Packages-Xorg
profile.conf

xfce-overlay: After every successful installation of your ISO (XFCE) the files and folders in here will get copied over.
isolinux: Contains files important for booting your ISO. This includes isolinux.cfg file to start syslinux bootloader.
mkinitcpio.conf holds the information of all needed kernel modules.
overlay: Similar to xfce-overlay, but it contains files and folders important to all Manjaro installations and LiveCDs.
overlay-livecd: Similar to xfce-overlay. Files and folders in here will only get copied over to the LiveCD of your ISO.
Packages: This file contains base packages important to all Manjaro installations and LiveCDs.
Packages-Livecd: This file contains packages, which will only get installed on the LiveCD.
Packages-Xfce: This file contains packages specific to your ISO (XFCE) installation. All packages will also get installed on LiveCDs.
Packages-Xorg: This file contains Xorg packages important to all Manjaro installations and LiveCDs.
profile.conf contains basic settings for your ISO installation and LiveCD.

As you have probably noticed, most files and folders are only symlinks to the shared ISO profile. It is good practice to never change files or folders in the shared ISO profile. If you ever want to change them, first copy them to your ISO profile folder and delete the symlink.

All folders and files specific to your ISO (in this example XFCE) are marked. You can change them to your liking.

Modifying an ISO profile

The most common places to tweak and customize an ISO profile are the 3 folders marked above: xfce-overlay, profile.conf, Packages-Xfce:

xfce-overlay

The xfce-overlay folder looks like this (hidden files are not shown):

├── etc
│   ├── lightdm
│   │   └── lightdm-gtk-greeter.conf
│   ├── mdm
│   │   └── custom.conf
│   └── skel
└── usr
    └── share
        ├── backgrounds
        │   └── lightdm
        │       └── manjaro-lightdm-gtk-greeter.jpg
        ├── icons
        │   └── default
        │       └── index.theme
        └── xfce4
            └── backdrops
                └── default.jpg -> /usr/share/backgrounds/manjaro.jpg

After the XFCE ISO has been successfully installed all files and folder in xfce-overlay folder get copied over to the installed system. This includes settings/config files but also themes and backgrounds/pictures.

There is one special folder (marked above):

manjaro-tools-iso-profiles/xfce/xfce-overlay/etc/skel

All files and folder in here will get copied to the home folder. Most hidden files and their structure in manjaro-tools-iso-profiles/xfce/xfce-overlay/etc/skel/ should be already familiar to you, because your home folder looks very similar.

profile.conf

##########################################
###### use this file in the profile ######
##########################################

# possible values: openrc,systemd
initsys="systemd"

# use multilib packages; x86_64 only
# multilib="true"

displaymanager="sddm"

# Set to false to disable autologin in the livecd
# autologin="true"

# nonfree xorg drivers
# nonfree_xorg="true"

# use plymouth; initcpio hook
# plymouth_boot="true"

# use pxe boot; initcpio hook
pxe_boot="false"

################ install ################

# unset defaults to given value
# kernel="linux318"

# unset defaults to given value
# efi_boot_loader="grub"

# set uefi partition size
# efi_part_size=31M

# unset defaults to given value
# plymouth_theme=manjaro-elegant

# unset defaults to given values
# names must match systemd service names
# start_systemd=('bluetooth' 'cronie' 'ModemManager' 'NetworkManager' 'org.cups.cupsd' 'tlp' 'tlp-sleep')
 
...

This config file contains setting options. All default settings are commented. If you want to change them, uncomment them (remove the # symbol in front) and change it.

The following settings are noteworthy:

initsys= lets you choose between systemd and OpenRC. This setting is associated with the >systemd and >openrc flags in your package lists.
multilib= setting belongs to the >multilib flag in your package lists. multilib will install basic 32bit libraries on 64bit systems. This increases compatibility for 32bit applications on 64bit systems.
displaymanager= sets the display / login manager your system uses. You need to list your display manager in your package list, too.
nonfree_xorg= refers to proprietary graphics drivers.
plymouth_boot= lets you activate Plymouth (the graphics displayed during boot). Do not forget the playmouth package in your package list.
pxe_boot= activates PXE boot on your system.
kernel= lets you set the installed kernel. Do not include any kernels in your package list! This setting is all you need.
start_systemd= let's you set systemd services, which get started on the installed system and on the livecd. A similar setting is available for OpenRC.

Packages-Xfce

### Manjaro Packages

## XFCE Main Packages
ffmpegthumbnailer
gconf                    # fix qt-theme
gnome-keyring            # fix wlan segfault
gufw                     # firewall
# mdm-themes
accountsservice
lightdm-gtk-greeter
lightdm-gtk-greeter-settings
light-locker
manjaro-settings-manager
>i686 gcc
>x86_64 gcc-multilib

...

This file contains a list of packages, which will get installed on the your installed ISO (XFCE) and the LiveCD. This is a package list with Xfce specific packages (and packages you like to add to your custom Manjaro ISO) of multiple package lists in your ISO profile. The other package lists are more generic.

You can add or remove package names from this list as you like. You do not need to worry about dependencies when adding package names, just make sure the package name is spelled correctly and the package is available in the Manjaro repositories.

# marks a comment. The rest of the line after the # symbol gets ignored.

>i686 is a flag and marks a package, which will only get installed on the 32bit version of your ISO (XFCE).

>x86_64 marks a package, which will only get installed on the 64bit version of your ISO (XFCE).

Adding AUR packages

If you want to add AUR packages to your ISO, you need to create a local repository and add it to the right pacman-XXXXX.conf file in your ISO profile.

There are two different ways to achieve this:

Buildiso with AUR packages: Using yaourt: This way is easier and faster, but has some disadvantages: First, all packages get installed on your real/host system, too. Second, you can only build packages for your system architecture. This means you cannot build 32bit packages on a 64bit system.
Buildiso with AUR packages: Using buildpkg: This way is a little harder and needs more build time. You can easily build and include 32bit packages, even if your host system is 64bit. All packages get installed in a separate build environment and do not affect your real / host system.

manjaro-tools.conf

manjaro-tools.conf is the central configuration file for all tools part of manjaro-tools. Only edit the general and the "buildiso" part to not exceed the scope of this tutorial. If you are not sure what and how to edit it, do not edit it. You can always use arguments with the buildiso command later.

By default, the systemwide config file is installed in

/etc/manjaro-tools/manjaro-tools.conf

Additionally, a userconfig manjaro-tools.conf file can be placed in your home directory here:

~/.config/manjaro-tools.conf

If the userconfig is present, manjaro-tools/buildiso will load the userconfig values, however, if variables have been set in the systemwide config file, these values take precedence over the userconfig. Best practice is to leave the systemwide file untouched. By default it is commented and shows just initialization values done in code.

Build your ISO

Navigate to the manjaro-tools-iso-profiles folder:

cd manjaro-tools-iso-profiles

Query the settings of buildiso and pretend to build your ISO with the -q argument. This also gives you a nice overview of what is going to happen:

sudo buildiso -p openbox -q

You need to specify the name of your ISO profile after the -p argument. In this case, it is openbox.

Then, start to build your ISO for real (just remove the -q argument):

sudo buildiso -p openbox

If the build process fails with an error, start it again.

Attention: The build process needs at least 10 minutes to complete or much longer when you are using HDDs, slow CPUs, or large ISOs.

When the build process finishes successfully, the ISO file and the package list will appear in this folder:

/var/cache/manjaro-tools/iso/

Example:

You can use arguments with the buildiso command for more build options:

sudo buildiso -p xfce-minimal -a i686 -b unstable -q

-a let's you build for other architectures. Here, it builds a 32bit ISO image on a 64bit host system. You can also set this in your manjaro-tools.conf file.
-b let's you specify the branch. You can also set this in your manjaro-tools.conf file.

You can find other examples of builds using different arguments for buildiso here.

Cleaning your hard drive

After a successful or failed build, you can get rid of most data (the "raw" ISO with all downloaded packages) by deleting this folder:

sudo rm -r /var/lib/manjaro-tools/buildiso/openbox/

To clean your system of packages files downloaded only for your custom ISO:

paccache -ruk0

You can also manually look into

/var/cache/manjaro-tools/

and delete folders or files to your liking. If you want to delete all ISO images, package lists, and cached Xorg packages do:

sudo rm -r /var/cache/manjaro-tools/

Please remember that all these packages and files are saved for your convenience. If you clean your system like suggested above, you have to download all packages and build all images again the next time you want to build your own Manjaro ISO.

@@ Line 290: / Line 290: @@
   sudo buildiso -p openbox -q
-You need to specify the name of your ISO profile, too. In this case, it is <code>openbox</code>.
+You need to specify the name of your ISO profile after the <code>-p</code> argument. In this case, it is <code>openbox</code>.
 Then, start to build your ISO for real (just remove the <code>-q</code> argument):
@@ Line 312: / Line 312: @@
   sudo buildiso -p xfce-minimal -a i686 -b unstable -q
-* <code>-a</code> let's you build for other architectures. Here, it builds a 32bit ISO image on a 64bit host system.
+* <code>-a</code> let's you build for other architectures. Here, it builds a 32bit ISO image on a 64bit host system. You can also set this in your <code>manjaro-tools.conf</code> file.
 * <code>-b</code> let's you specify the branch. You can also set this in your <code>manjaro-tools.conf</code> file.

Difference between revisions of "Build Manjaro ISOs with buildiso"