How to build PetaLinux in offline mode

In certain scenarios, you might want to build PetaLinux without relying on an active internet connection. This offline building feature can be useful for various reasons. To build PetaLinux without a network connection, you obviously need pre-downloaded source packages and dependencies. Xilinx allows you to pre-download all of these dependencies (called sstate cache artefacts) and then perform the build offline.

Why You Would Use It

The reason to use offline mode really depends on your situation and it’s definitely not something that everyone will get benefit from. However there are some reasons why you might want to consider it:

1. Security Concerns: In high-security environments, machines may be deliberately kept offline or isolated from the internet to prevent unauthorized access or data leaks. If this is your case, you have no choice but to use offline mode.

2. Stable Environment: Ensuring that all dependencies are pre-downloaded allows for a consistent build environment. You don’t have to worry about packages getting updated midway or repositories going down during a build. I have personally had problems trying to build PetaLinux for PYNQ where the dependencies had been updated and were now causing build failures.

3. Bandwidth Limitations: In areas with limited or unreliable internet connectivity, having the ability to build offline can save you some headaches. When a PetaLinux build crashes because of internet connectivity issues, you will probably be pulling your hair out trying to figure out why it happened, because the messaging in these cases can be cryptic.

Benefits

1. Consistency: All builds will use the same version of sources and dependencies, eliminating variability introduced by updated packages or differing repository states.

2. Security: Reduced risk of middle-man attacks, unauthorized data access, or other vulnerabilities associated with online communications.

3. Speed: Build processes may be faster without the overhead of downloading packages. This is the main reason that I personally use offline build, but I typically have to build many projects for many different platforms, so the time saved is significant.

Cons

1. Setup Time: You need to download and install the sstate cache artefacts. It takes some time but it’s much less than it takes to install the PetaLinux tools themselves.

2. Storage: All the packages and dependencies need to be stored locally, which can take up a significant amount of disk space. To give you an idea, for PetaLinux 2022.1, the sstate cache artefacts use up a total of 76.5GB.

3. Lack of Automatic Updates: Working offline means you won’t get the latest patches or updates unless you manually integrate them into your offline environment.

How to setup a machine for offline build

To prepare a machine to build PetaLinux without a network, you need a machine with a network connection in order to download the required files.

1. Download the sstate-cache artefacts from the Xilinx downloads site, which is the same page from which you would have downloaded the PetaLinux tools. There are four sstate-cache artefacts, and you will need to download all of the ones that you need, depending on the devices for which you are building PetaLinux:
   • aarch64 sstate-cache (for ZynqMP designs)
   • arm sstate-cache (for Zynq designs)
   • microblaze sstate-cache (for MicroBlaze designs)
   • Downloads (for all designs)
2. Extract the contents of those files to a single location on the hard drive of the machine that you will use to build PetaLinux in offline mode. In this example let’s extract those files to /home/user/petalinux-sstate. That will leave you with the following directory structure:

   /home/user/petalinux-sstate
                             +---  aarch64
                             +---  arm
                             +---  downloads
                             +---  microblaze

3. Now your machine is ready to build PetaLinux offline, but in order to tell the tools to build a project in offline-mode, you need to specify it at the project level, in the main configuration file. In the project-spec/configs/config file of the PetaLinux project that you want to build offline, append the following two lines:

   CONFIG_PRE_MIRROR_URL="file://<SSTATE_PATH>/downloads"
   CONFIG_YOCTO_LOCAL_SSTATE_FEEDS_URL="<SSTATE_PATH>/<SSTATE_ARCH>"

   You will need to replace <SSTATE_PATH> with the path of the sstate artefacts that you extracted earlier. You also need to replace <SSTATE_ARCH> with the processor architecture type:
   • For Zynq-7000 projects: arm
   • For Zynq UltraScale+ projects: arch64
   • For Microblaze projects: microblaze For example, using our example path and a Zynq-7000 project, the configuration lines would be:

   CONFIG_PRE_MIRROR_URL="file:///home/user/petalinux-sstate/downloads"
   CONFIG_YOCTO_LOCAL_SSTATE_FEEDS_URL="/home/user/petalinux-sstate/arm"

   Alternatively, you can use the menuconfig and make those same configurations, but I’ve shown you how to directly modify the config file so that you will better understand the next part of this post: how to build this into your scripts as an option.

Scripting offline mode as an option

In my work, I have to maintain a lot of PetaLinux projects. The builds are done through Makefiles that check all of the dependencies and allow myself and the customer to launch the entire build process with a single command. If you want to see an example Makefile, checkout the one from this project.

Usually when I launch a build, I want it to be done in offline-mode, but for the customer, it’s not usually required. So this is how I’ve made “offline-build” an option that can be enabled for a project if it is needed.

To enable the offline-build:

• The machine needs to be setup as I explained above (with the sstate artefacts extracted).
• A text file needs to be created in the project folder containing the path of the sstate artefacts. I’ve called this file offline.txt and it can be added to the .gitignore file or whatever is relevant for your flavor of version control. For example, my offline.txt file could contain this single line:

  /home/user/petalinux-sstate

• The Makefile needs to check for the existence of the offline.txt text file, and if it exists, it needs to read the path from text file and append the configuration lines to the PetaLinux project config file.

Here is the part of the Makefile that reads the offline.txt text file and creates the two lines to be appended to the config file:

# Path to the offline.txt file containing the path of the sstate artefacts
PETL_OFFLINE = $(PETL_ROOT)/offline.txt

# Path to the sstate artefacts, read from the offline.txt file (if it exists)
SSTATE_PATH ?= $(shell test -e $(PETL_OFFLINE) && head -n 1 $(PETL_OFFLINE))

# If we have a path for sstate artefacts, then create the two config lines to append later
# (note that this is assuming that the project is for Zynq-7000)
ifneq ($(SSTATE_PATH),)
	MIRROR_URL = CONFIG_PRE_MIRROR_URL="file://$(SSTATE_PATH)/downloads"
	SSTATE_FEEDS = CONFIG_YOCTO_LOCAL_SSTATE_FEEDS_URL="$(SSTATE_PATH)/arm"
endif

Later, in the build rule, the Makefile can append the config lines if it found the offline.txt file containing the path to the sstate artefacts. Here is an example:

build: 
	@if [ ! -z "$(SSTATE_PATH)" ]; then \
		echo '$(MIRROR_URL)' >> ./$(TARGET)/project-spec/configs/config; \
		echo '$(SSTATE_FEEDS)' >> ./$(TARGET)/project-spec/configs/config; \
		echo 'Configuring project for offline build'; \
	fi

I’ve found it useful to apply the offline-build option through the Makefile in this way because:

• It is completely transparent to the customer; they don’t even need to know that the option exists.
• The configs are not applied to version controlled sources, so you wont mix up important config changes with these temporary/optional ones.

I hope you find this useful. If my explanation here was not quite clear enough, you can always clone the Git repo and examine the project and sources in more detail.