Upgrade from CC Linux 3 to CC Linux 5

CC Linux version 5 takes robustness and cyber security one step further. With stronger control of the file system on the display and the introduction of the RAUC update process, there are a few differences to consider compared to CC Linux version 3. In this guide we will give some tips and recommendations to follow when an application currently built for CC Linux 3 will be deployed on CC Linux 5.

Differences

The table below shows the root directories of the two CC Linux OS versions.

CCL 3	/	CCL 5	/
-	-	drwxr-xr-x	appfs
drwxr-xr-x	bin	lrwxrwxrwx	bin -> usr/bin
drwxr-xr-x	boot	drwxr-xr-x	boot
-	-	drwxr-xr-x	data
drwxr-xr-x	dev	drwxr-xr-x	dev
drwxr-xr-x	etc	drwxr-xr-x	etc
drwxr-xr-x	home	drwxr-xr-x	home
drwxr-xr-x	lib	lrwxrwxrwx	lib -> usr/lib
drwx——	lost+found	drwx——	lost+found
drwxr-xr-x	media	lrwxrwxrwx	media -> data/media
drwxr-xr-x	mnt	drwxr-xr-x	mnt
drwxrwxrwx	opt	-	-
dr-xr-xr-x	proc	dr-xr-xr-x	proc
-	-	drwx——	root
drwxr-xr-x	run	drwxr-xr-x	run
drwxr-xr-x	sbin	lrwxrwxrwx	sbin -> usr/sbin
drwxr-xr-x	srv	drwxr-xr-x	srv
dr-xr-xr-x	sys	dr-xr-xr-x	sys
drwxrwxrwt	tmp	drwxrwxrwt	tmp
drwxr-xr-x	unit_tests	drwxr-xr-x	unit_tests
drwxr-xr-x	usr	drwxr-xr-x	usr
drwxr-xr-x	var	drwxr-xr-x	var

Noticeable differences are:
The /opt directory is not available in CCL 5.
The /appfs and /data directories have been added in CCL 5. There is also a /root directory in CCL 5 that does not play any significant role in application deployment.

In short words, the general purpose /opt directory is divided into /appfs (applications, libraries, binaries, services, etc.) and /data (ini files, user data, logs, settings, dynamic data, etc.).

The /etc directory is partly part of the rootfs image and partly mapped to /data/cc-etc. This means that the /etc directory and its contents are preset in the OS but can be altered through a RAUC bundle or root access for additions and adaptations on OS level. All post-edits of the /etc directory will be linked into the /data/cc-etc file layer.

Note Do not make edits in the /data/cc-etc directory directly! Use the standard /etc entry. The linking will take care of the file management.

File Structure in CCL 5

The /appfs is write protected, i.e. it is mounted in read-only mode and requires root access to unlock and edit.

Per default, the /appfs contains the following structure, but normally it is replaced by a custom application file structure via a RAUC bundle. See the RAUC guide for more information about RAUC installation procedures.

	/appfs
lrwxrwxrwx	bin -> usr/bin
drwxr-xr-x	etc
lrwxrwxrwx	lib -> usr/lib
drwx——	lost+found
drwxr-xr-x	run
lrwxrwxrwx	usr/sbin
drwxr-xr-x	usr
drwxr-xr-x	var

The /data directory is writable with root access and contains the following directory structure:

	/data
drwxr-xr-x	cc-etc
drwxr-xr-x	cc-workdir
drwxr-xr-x	home
drwx——	lost+found
drwxr-xr-x	media
drwxr-xr-x	rauc

The currently logged in ccs user has access to the /data/home/ccs directory. This is the home directory of the user where application settings, user data, logs and other dynamic contents can be stored.

Deploying an Application

In CCL 5, the processor type for the iMX8 based CCpilot displays has changed from aarch64 to cortexa35. Also the default install path needs to be updated to a writable directory on CCL 5 instead of the /opt/appMyApp/bin directory. CMakeLists.txt can be updated in the following way:

Change install target directory, something like this:

set(TARGET_INSTALL_DIR "/opt/appMyApp/${CMAKE_INSTALL_BINDIR}")

To:

set(TARGET_INSTALL_DIR "/data/home/ccs/appMyApp/${CMAKE_INSTALL_BINDIR}")

With legacy/backwards compatibility:

if (CMAKE_SYSTEM_PROCESSOR STREQUAL "cortexa35")
    set(TARGET_INSTALL_DIR "/data/home/ccs/appMyApp/${CMAKE_INSTALL_BINDIR}")
else()
    set(TARGET_INSTALL_DIR "/opt/appMyApp/${CMAKE_INSTALL_BINDIR}")
endif()

if (CMAKE_SYSTEM_PROCESSOR STREQUAL "aarch64" OR CMAKE_SYSTEM_PROCESSOR STREQUAL "cortexa35")
    message("Building for iMX8")
endif()

Systemd services

Systemd service scripts can be put in the /appfs/lib/systemd/system directory. To enable a service, it is convenient to make a link to the service in the /appfs/lib/systemd/system/multi-user.target.wants directory using the RAUC bundle install.

Application Settings and Dynamic Data

If the application has an application settings file or other data written from the application, the paths need to be changed from /opt, or any other directory, to the /data/home/ccs.

Splash screen

Splash screen developed using PSplash can be copied as usual to the /etc directory during installation.

Fieldbus Access and Data Engine

Fieldbus Access and Data Engine are available as tar.gz files, which can be embedded into a RAUC bundle. The packages can either be extracted already before the bundle is created, or extracted on the target display using a hook script with the output path set to the /appfs directory.

Qt Creator & QML

The Qt Runtime is preferably put in the /appfs/qt6 directory.

Debug and Development

As mentioned above, running a Qt application from Qt Creator needs a writable directory on the target display, for example the /data/home/ccs/appMyApp directory. You may need to create the directory manually.

Summary

A complete deployment of the appMyApp developed using Qt6 with Data Engine, Fieldbus Access, service scripts, settings file(s) and a splash screen could look like this:

.
├── appfs
│   ├── bin
│   │   ├── appMyApp
│   │   ├── dataengineserverApp
│   │   ├── fieldbusaccess
│   │   └── LinXManager_FA_configfile.json
│   ├── lib
│   │   ├── libsapcore.so -> libsapcore.so.3.1.4
│   │   ├── libsapcore.so.3 -> libsapcore.so.3.1.4
│   │   ├── libsapcore.so.3.1 -> libsapcore.so.3.1.4
│   │   ├── libsapcore.so.3.1.4
│   │   └── systemd
│   │       └── system
│   │           ├── appMyApp.service
│   │           ├── dataengine.service
│   │           ├── fieldbusaccess.service
│   │           └── multi-user.target.wants
│   │               ├── appMyApp.service -> ../appMyApp.service
│   │               ├── dataengine.service -> ../dataengine.service
│   │               └── fieldbusaccess.service -> ../fieldbusaccess.service
│   └── qt6
│       ├── bin
│       │   └── ...
│       ├── lib
│       │   └── ...
│       ├── plugins
│       │   └── ...
│       └── ...
├── data
│   └── home
│       └── ccs
│           └── appMyApp-settings.ini
├── etc
│   ├── psplash
│   ├── psplash-write
│   └── ...
└── ...

Tips & Tricks

Use embedded resources for custom application fonts in Qt, so they do not need to be installed on the rootfs.