[Wiki] How to contribute to Manjaro ARM

[Wiki] Contributing to Manjaro-ARM

Over the past few years of Manjaro-ARM’s existence, we have had several people offer to help or at least show interest to help. While we appreciate every offer, it seems one of the largest issues that comes about is a large disconnect between the people wanting to help and the procedures to actually get anything done. We have made it extremely simple to do basic functions for manjaro-arm to mitigate the whole “Dont know how to do” or the “Dont know what to do”. This wiki post will hopefully solve this.

This post also serves as a service to allow standard users to create their own images or packages. Almost everything we do to get an image created for the devices supported can be done by a user with just a few commands.

It really is that simple

Requirements

  • Manjaro running on an x86_64 machine
  • Manjaro-arm-tools

Manjaro-arm-tools

Installing package

Manjaro has been kind enough to include this package in the repo so it can be installed with pacman.

$ sudo pacman -S manjaro-arm-tools

Installing git package

There is also a git version of the tools that has the most updated support for new boards and new options as we add them. This can be installed through Strit’s repo

Add strit’s repo to your pacman.conf

$ sudo nano /etc/pacman.conf

and add these lines to the bottom:

[manjaro-strit]
SigLevel = Never
Server = https://www.strits.dk/files/manjaro-strit/manjaro-strit-repo/$arch 

Sync package lists and install the git package

$ sudo pacman -Syy manjaro-arm-tools-git

Layout of the tools and how it works

There are several main functions of the manjaro-arm-tools.

  • buildarmimg - Utility for building images that include the oem installer for configuration on first boot
  • buildarmpkg - this is for building single packages from a PKGBUILD
  • buildemmcinstaller - This builds new pinebook images (and other devices) that includes the emmc flasher
  • buildrootfs - Builds a rootfs for user for a variety of reasons
  • getarmprofiles - Retrieves the current arm profiles used for building images

All of these utilities are meant to be run on a standard x86_64 machine such as a desktop/laptop and make use of a virtualization tool called qemu.

We have created rootfs which is a bare skeleton of Manjaro-ARM that will be downloaded, ‘started’ using qemu and systemd-nspawn, and configured with the tools above. Once the tools package is installed, there is a configuration located at:

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

that contains build directories and output directories. By default, this does not need to be altered.

Getting Profiles

Profiles are mainly text files that contain lists of packages and settings that get installed and configured on images that are built for Manjaro-ARM. They allow us to set themes, start services, add taskbar applets, default settings and much more. They originate from Manjaro’s own profiles and are altered a bit to work on ARM boards. They are installed at

/usr/share/manjaro-arm-tools/profiles

Usage

$ sudo getarmprofiles -f

Editing profiles for customization

If you are wanting to begin work on a new profile for a desktop environment we don’t yet support, this is the first step. Creating new profiles to be used in the builds is pretty easy and can be achieved by using one of the pre-existing examples already in place. Below is the directory tree of the profiles and how the are structured.

  • Devices contains lists of packages that are required for each device in order to get them to work on any edition
  • Edition contains the list of packages that required for the desktop editions that we support.
  • Overlays are example configuration files that contain the manjaro-specific settings and options. They are structured exactly as they would be as installed on the device.
  • Services is simply a list of systemd services that should be enabled by default. They are specific to the desktop edition being used.
├── devices
│   ├── nanopc-t4
│   ├── oc2
│   ├── oc4
│   ├── on2
│   ├── on2-plus
│   ├── pbpro
│   ├── pine64
│   ├── pine64-lts
│   ├── pinebook
│   ├── pinephone
│   ├── pinetab
│   ├── rock64
│   ├── rockpi4
│   ├── rockpro64
│   ├── rpi3
│   ├── rpi4
│   ├── vim1
│   ├── vim2
│   └── vim3
├── editions
│   ├── cubocore
│   ├── gnome
│   ├── i3
│   ├── kde-plasma
│   ├── lxqt
│   ├── mate
│   ├── minimal
│   ├── plasma-mobile
│   ├── server
│   ├── wayfire
│   └── xfce
├── overlays
│   ├── cubocore
│   │   ├── etc
│   │   │   ├── environment
│   │   │   ├── pulse
│   │   │   │   └── default.pa
│   │   │   ├── sddm.conf
│   │   │   ├── skel
│   │   │   └── xdg
│   │   │       └── autostart
│   │   │           └── corestuff.desktop
│   │   └── overlay.txt
│   ├── gnome
│   │   ├── etc
│   │   │   ├── environment
│   │   │   ├── hosts
│   │   │   ├── modprobe.d
│   │   │   │   └── blacklist-panfrost.conf
│   │   │   ├── NetworkManager
│   │   │   │   └── conf.d
│   │   │   │       └── dhcp-client.conf
│   │   │   ├── pulse
│   │   │   │   └── default.pa
│   │   │   ├── sddm.conf
│   │   │   ├── skel
│   │   │   │   ├── Templates
│   │   │   │   │   └── File.txt
│   │   │   │   └── Trash
│   │   │   │       ├── trash.sh
│   │   │   │       ├── user-trash-full.svg
│   │   │   │       └── user-trash.svg
│   │   │   └── systemd
│   │   │       ├── journaldjournald.conf
│   │   │       └── system
│   │   │           └── multi-user.target.wants
│   │   │               └── remove-classic.service -> /usr/lib/systemd/system/remove-classic.service
│   │   ├── overlay.txt
│   │   └── usr
│   │       ├── lib
│   │       │   └── systemd
│   │       │       └── system
│   │       │           └── remove-classic.service
│   │       ├── local
│   │       │   └── bin
│   │       │       └── remove-classic.sh
│   │       └── share
│   │           └── icons
│   │               └── manjaro-logo.svg
│   ├── i3
│   │   └── etc
│   │       ├── fonts
│   │       │   └── conf.d
│   │       │       └── 70-no-bitmaps.conf -> /etc/fonts/conf.avail/70-no-bitmaps.conf
│   │       ├── lightdm
│   │       │   ├── lightdm.conf
│   │       │   └── lightdm-gtk-greeter.conf
│   │       ├── pamac.conf
│   │       ├── polkit-1
│   │       │   └── rules.d
│   │       │       └── 81-blueman.rules
│   │       └── X11
│   │           └── xorg.conf.d
│   │               └── 30-touchpad.conf
│   ├── kde-plasma
│   │   ├── etc
│   │   │   ├── environment
│   │   │   ├── pamac.conf
│   │   │   ├── pulse
│   │   │   │   └── default.pa
│   │   │   ├── sddm.conf
│   │   │   └── skel
│   │   ├── overlay.txt
│   │   └── usr
│   │       └── share
│   │           └── konsole
│   │               └── Profile 1.profile
│   ├── lxqt
│   │   ├── etc
│   │   │   ├── environment
│   │   │   ├── hosts
│   │   │   ├── NetworkManager
│   │   │   │   └── conf.d
│   │   │   │       └── dhcp-client.conf
│   │   │   ├── pamac.conf
│   │   │   ├── pulse
│   │   │   │   └── default.pa
│   │   │   ├── sddm.conf
│   │   │   ├── skel
│   │   │   └── systemd
│   │   │       └── journald.conf
│   │   └── overlay.txt
│   ├── mate
│   │   ├── etc
│   │   │   ├── environment
│   │   │   ├── hosts
│   │   │   ├── lightdm
│   │   │   │   └── lightdm-gtk-greeter.conf
│   │   │   ├── NetworkManager
│   │   │   │   └── conf.d
│   │   │   │       └── dhcp-client.conf
│   │   │   ├── pamac.conf
│   │   │   ├── pulse
│   │   │   │   └── default.pa
│   │   │   ├── skel
│   │   │   └── systemd
│   │   │       └── journald.conf
│   │   └── overlay.txt
│   ├── minimal
│   │   └── overlay.txt
│   ├── plasma-mobile
│   │   ├── etc
│   │   │   ├── sddm.conf
│   │   │   ├── skel
│   │   │   └── xdg
│   │   │       ├── kdeglobals
│   │   │       └── kwinrc
│   │   └── overlay.txt
│   ├── server
│   │   └── overlay.txt
│   ├── wayfire
│   │   ├── etc
│   │   │   ├── environment
│   │   │   ├── sddm.conf
│   │   │   └── skel
│   │   └── overlay.txt
│   └── xfce
│       ├── etc
│       │   ├── environment
│       │   ├── hosts
│       │   ├── lightdm
│       │   │   └── lightdm-gtk-greeter.conf
│       │   ├── NetworkManager
│       │   │   └── conf.d
│       │   │       └── dhcp-client.conf
│       │   ├── pamac.conf
│       │   ├── pulse
│       │   │   └── default.pa
│       │   ├── skel
│       │   └── systemd
│       │       └── journald.conf
│       ├── overlay.txt
│       └── usr
│           └── share
│               └── icons
│                   └── manjaro-logo.svg
└── services
    ├── cubocore
    ├── gnome
    ├── i3
    ├── kde-plasma
    ├── lxqt
    ├── mate
    ├── mate-fta
    ├── minimal
    ├── plasma-mobile
    ├── server
    ├── wayfire
    └── xfce

Note armv7 devices are no longer supported and will be removed soon

Building an OEM image

An OEM image is an image that contains the Manjaro-ARM OEM installer. It is the only images that will be made from this point forward. The OEM installer allows the user to setup up username, passwords, locale, and keyboard layout upon the first boot. This removes the need for the user to have to change the default settings. The OEM installer is installed as a package and automatically runs on first boot as root user (which is automatically logged in upon boot). Once the installer is finished and the system is configured to the user’s specification, the installer is removed from the system.

Usage

Usage: buildarmimg [options]
    -d <device>        Device the image is for. [Default = rpi4. Options = oc2, on2, on2-plus, pbpro, pine64, pine64-lts, pinebook, pinephone, pinetab, rock64, rockpi4, rockpro64, rpi3, rpi4, vim1, vim2, vim3]
    -e <edition>       Edition of the image. [Default = minimal. Options = cubocore, gnome, i3, kde-plasma, lxqt, mate, minimal, plasma-mobile, server, wayfire, xfce]
    -v <version>       Define the version the resulting image should be named. [Default is current YY.MM]
    -i <package>       Install local package into image rootfs.
    -b <branch>        Set the branch used in the image. [Default = stable. Options = stable, testing or unstable]
    -n                 Force download of new rootfs.
    -x                 Don't compress the image.
    -h                 This help

Example

To build an kde-plasma image for the Odroid-n2:

$ sudo buildarmimg -d on2 -e kde-plasma -v myfirstbuild -n

Result

The above command will take a few minutes depending on internet connection and speed of computer but will result in an image inside of a compressed xz container. You can use -x to output a full image if desired.

As this command is being executed, several processes take place. It first downloads a new aarch64 rootfs from one of the manjaro-arm mirrors and extracts it. Using qemu and systemd-nspawn, the script chroots into the rootfs and lets us use it as a working arm install. The utility then installs all the profile packages, sets all the overlay settings, and enables all services according to the profile.

After everything is installed, it creates and mounts a loop device on your system in order to create required partitions (root and/or boot) and copies everything into these partitions. It will then flash any boot specific binaries or files into the correct location on the loop device. Once everything is finished, it dumps the loop device (containing the partitions and correct boot binaries all properly located) into an image file. The final step compresses the image into the .xz format.

Once the xz is is created, everything is cleaned up and the loop device removed.

If everything worked as planned, you will be left with a flashable image named:

Manjaro-ARM-kde-plasma-on2-myfirstbuild.img.xz

You can find this image at

/var/cache/manjaro-arm-tools/img/

Everything is done automatically and as such, is thoroughly tested. If problems do arise, we are generally quick to fix it.

Building an EMMC - installer image

The eMMC installer image is very similar to the oem image. It essentially creates a minimal image for a device but also downloads a released version of Manjaro-ARM from OSDN and stores it within the image. It is mainly used for the pinebook as it has an eMMC inside of the laptop that requires disassembly to access. Instead of an OEM installer being executed upon first boot, there is instead a flash utility with a few user prompts in order to flash to the internal eMMC. This image is basically useless for anything else.

Right now, it works on the pinebook however, should also work on other devices that have both an eMMC and SDCard and can boot from both.

Usage

Usage: buildemmcinstaller [options]
    -d <device>        Device the image is for. [Default = rpi4. Options = oc2, on2, pbpro, pine64, pine64-lts, pinebook, pinephone, pinetab, rock64, rockpi4, rockpro64, rpi3, rpi3-fta, rpi4, vim1, vim2, vim3]
    -e <edition>       Edition of the image to download. [Default = minimal. Options = cubocore, gnome, i3, kde-plasma, lxqt, mate, mate-fta, minimal, plasma-mobile, server, wayfire, xfce]
    -v <version>       Define the version of the release to download. [Default is current YY.MM]
    -f <flash version> Version of the eMMC flasher image it self. [Default is current YY.MM]
    -i <package>       Install local package into image rootfs.
    -n                 Force download of new rootfs.
    -x                 Don't compress the image.
    -h                 This help

Example

To build a emmc-installer image for the pinebook using Manjaro-ARM-lxqt-19.03:

$ sudo buildemmcinstaller -d pinebook -e lxqt -v 19.03 -f first_emmc_build -n

Note here the -v option is required in order to obtain the correct version of Manjaro-ARM.
Note 2: the eMMC installer images are no longer used.

Result

Like the buildoem tool above, all the same processes are performed as it would be for a minimal image. the result will be named:

Manjaro-ARM-lxqt-19.03-first_emmc_build.img.xz

located in the same directory:

/var/cache/manjaro-arm-tools/img/

Building a Package

This tool allows us to build our arm packages on our x86_64 computers without having to have a working device. It uses systemd-nspawn and qemu to virtualize an ARM device much like the image building tools. This is useful for packages that take a long time to build and you dont want to tie up your device for simply building.

Even though our x86_64 machines are more powerful, qemu does not allow us to use this power to the full extent. Packages often take longer to build using this method vs building them on a powerful device such as the rockpro64.

Usage

Usage: buildarmpkg [options]
    -a <arch>          Architecture. [Default = aarch64. Options = any or aarch64]
    -p <pkg>           Package to build
    -k                 Keep the previous rootfs for this build
    -b <branch>        Set the branch used for the build. [Default = stable. Options = stable, testing or unstable]
    -i <package>       Install local package into rootfs.
    -h                 This help

Example

It will only build packages that have a proper PKGBUILD. This means that the PKGBUILD needs to have the correct architecture, depends, and makedepends before continuing. Please refer to information on PKGBUILDs and makepkg for proper usage. You can also look at the manjaro-arm gitlab in order to see the PKGBUILDs we use.

To build linux

$ sudo buildarmpkg -p linux

Note that “linux” is the name of the directory that contains the PKGBUILD. This needs to be executed in the directory above the “linux” directory

Result

During this process, the rootfs is downloaded and extracted. Systemd-nspawn and qemu set it up as a basic virtualized environment. The entire directory containing the PKGBUILD will be copied into this environment and makepkg will be executed building your package. Standard outputs will be shown for troubleshooting purposes. If proper packages are defined in the PKGBUILD as makedepends, they will be installed as part of the build process.

If everything goes well, all pkg.tar.xz packages built from your PKGBUILD can be found at

/var/cache/manjaro-arm-tools/pkg/

Building a rootfs

This is more of an advanced tool. It simply builds a very minimal rootfs. The resulting rootfs only has pacman and dependencies so that it can be used to create images and packages. You would only want to use this if you know what you are doing and know how to manipulate the rootfs as you want.

Example

$ sudo buildrootfs

Result

You will have a rootfs that can be used to start working on unsupported devices, personal customizations, or whatever else you want.

You can find it at:

/var/cache/manjaro-arm-tools/img/

Other Information

Hopefully with this information, nobody will be lost as to how to build things for their arm devices. If there is a package that you wish for us to support, a desktop edition you would like to see, or any other additions to Manjaro-ARM that you have been waiting for, helping build it is a huge first step.

Please let us know if you come across any errors or unexpected behaviors.

Links

Manjaro-arm-tools
Manjaro-arm-oem-installer
Manjaro-arm-emmc-flasher
Manjaro-arm git
ARM profiles

PS: This post was copied from the forum archive.

14 Likes

HI,

Nice post, practice for everyone.

on2-plus added

:-)

This is awesome. Thanks @Strit.

However, thinking in terms of packages, this guidance mostly seems to relate to ‘helping me to help me’, rather than ‘helping me to contribute to Manjaro’. It would be good if you could include some stuff relating to what influences the decision making process at Manjaro ARM for things like adopting a new PKGBUILD, e.g. licensing, whether or not it matters if the PKGBUILD rebundles binaries (such as those suffixed by -bin in the AUR or must start from the package source, etc. Some PKGBUILDs might be dead on arrival for one or other reasons. In such circumstances, it might be good to point people to alternatives in the event that their package can’t be hosted on the Manjaro repos, such as Arch guidance on how to upload a PKGBUILD to the AUR.

1 Like

Regarding packages that get into the repo, it’s up to the Manjaro ARM maintainer if he wants to maintain it.
It requires a license that allows us to redistribute it, ofcourse, but in general it depends if a team member wants to maintain the package and maybe even use it in one of the edition he/she maintains.

Uploading packages to AUR, is not directly contributing to Manjaro ARM, but rather to Arch Linux eco-system in general and thus does not belong in a guide on how to contribute to us.

So, say hypothetically that I’d created a PKGBUILD that works on Manjaro ARM that I’d like to be considered for hosting in the Manjaro ARM repos (which actually happens to be the case). What do I do next? Also, who would be the “Manjaro ARM maintainer” in this context; me or one of the Manjaro ARM team, i.e. one of the Manjaro ARM team adopt it, or do I maintain it in a git repo, which the Manjaro ARM team fork?

I’m good with the building the package bit. I just don’t know what the next steps are. Currently, I don’t know what the process is to ask someone about hosting a package in here.

It would be one of our team members.
The team member would copy and maintain the PKGBUILD in our gitlab.

Thanks! my pine phone came two days ago, and I will be looking into exactly what you have posted, I just need to get some bug reporting done first.

My pine phone worked with only a few glitches the fist day, so I downloaded updates the second day and now almost every app is crashing and I get lots of black screen with a blinking cursor in the upper right I am still trying to learn “the way of the Linux”. Since there are not any stack traces or dumps as far as i can see I may need to take debugging to a deeper level just to report where and what bugs are going on.

Thanks again!

Hello and welcome to the forum,

You should post issues here