OS migration from arz 1.0 to Arz 1.1.x or Batz 2.x.x

This document presents evolutions and differences between redpesk versions from arz-1.0.x to arz-1.1.1 or later (since June 2023).

This chapter will first describe changes and then give you in the Migration checklist section the instructions you must follow to make your existing applications compatible with arz-1.1-update, arz-1.1.1 or later .

Changes

With the benefit of experience, the redpesk framework evolves.

The major changes are coming from reorganization of the application framework and improvement of helper libraries going with integration of bindings version 4.

This reorganization includes:

• change of installation directories;
• introduction of new manifest file for metadata of applications;
• refactor of afb-cmake-modules;
• refactor of afm-rpm-macros;
• simplification of development chain;
• refactor of helper libraries;
• refactor of security configuration method.

Change of installation directories

The main installation directory for applications is now /usr/redpesk instead of /var/local/lib/afm/applications.

In make’s files and cmake’s files, it is normalized that this directory must be referenced using the variable AFM_APP_DIR.

When afm-rpm-macros is used in SPEC files, the macro %_afmappdir is defined to point that location, and, the macro %afm_configure_cmake set the variable AFM_APP_DIR to the value of %_afmappdir.

The package afb-cmake-module uses now the variable AFM_APP_DIR instead of CMAKE_INSTALL_PREFIX.

Changes of afb-cmake-modules

That module is modified for using the variable AFM_APP_DIR normalized to be the root installation directories for applications.

Consequently, the variable CMAKE_INSTALL_PREFIX or other variables CMAKE_INSTALL_... have standard values.

In arz-1.0.x, it was defined at the root directory of the binding installation, now it is let at its conventional value (generally /usr) and allows to install a file anywhere.

A bug was fixed in setting of link properties. The older version was erasing any LINK_FLAGS property set using set_target_property. So because the current version allows incremental LINK_FLAGS to be set, you can have an error if you set -Wl,–version-script=…. in your CMakeLists.txt when defining bindings.
This error comes from duplication of linker script. If you reach that error, remove your -Wl,–version-script=… from your link flags.

Changes of afm-rpm-macros

The packaging macros available in SPEC files evolves accordingly to packaging changes.

• New macro %_afmappdir must be used for referring root directory where applications are installed. Its value is %{_prefix}/redpesk that is generally substituted by /usr/redpesk.

• The macro %_afmdatadir is now DEPRECATED and replaced by %_afmappdir. It is kept for compatibility but will be removed in a next version.

• The macro %afm_configure_cmake is reworked and simplified:
  • set AFM_APP_DIR to %_afmappdir
  • set BUILD_TEST_WGT to TRUE
  • does not modify PROJECT_VERSION, PROJECT_NAME anymore,
  • does not redefine CMAKE_INSTALL_PREFIX, CMAKE_INSTALL_LIBDIR, CMAKE_INSTALL_LIBEXECDIR

• The macro %afm_build_cmake is reworked and simplified. This evolution goes with the evolution of afb-cmake-modules.

• Remove former deprecated macros. Note that these removed macros were producing errors and then the removal should be transparent.

• Remove of some macros that were not deprecated but that were probably not used anymore:
  • %_wgtdir
  • %_afmname
  • %version_widget
  • %afm_autobuild_widget
  • %afm_install

Simplification of development chain

The new framework establishes a clear distinction between development material and running material. That new behaviour comes from accepting installation of files in traditional FHS 3.0 locations.

So pkgconfig files, include files and libraries can be installed in traditional locations. This is also permitted by the fact that afb-cmake-module now uses AFM_APP_DIR as root for redpesk application. So using CMAKE_INSTALL_PREFIX and all CMAKE_INSTALL_... have their traditional values and can be used for installing development files.

Refactor of helper and controller libraries

Integration of afb-binding version 4 and refactoring core of utility library implied refactoring of helpers library and of controller library.

Changes in controller library

The version 4 of the library libafb-helpers4 includes features for loading plugins while the binder has features for configuration extensions. These two features make controller library deprecated and so stuck to version 3 of bindings.

As such, libafb-controller should not be used in newer developments.

Changes in helper library

The helper library for bindings version 3 is not changed and can be used as before.

The helper library for bindings version 4 has deeply changed. It is now split in 2 parts:

• A generic utility C library named librp-utils, described below;

• A binding version 4 aware library named libafb-helpers4.

The library libafb-helpers4 depends of librp-utils and provides features for:

• making handling of afb_data values easier;

• sending request’s replies easier, with old binding v2 and v3 signatures;

• integration of plugins, plugins are shared libraries that are using binding’s features;

• controller like plugin feature.

Note also that helper library is now available as shared or static.

New utility library

The new library librp-utils provides statically or dynamically the following features:

• functions and macros for logging;

• integration of json-c wrapper, including a yaml reader, and some other JSON utilities;

• escaping of URLs and wrapping of CURL library;

• miscellaneous utilities: base64, variable expansion, file reading, file discovering, UUID, SHA1, socket naming, …

Refactor of security configuration method

This change does not impact the security policy that remains identical.

Internally, the security configuration data for Smack have been separated its packaging. From a packaging view, the RPM sec-smack-rules replaces the RPM smack-rules.

Dependency to smack-rules could remain, especially in kickstarts for smack security images. Consequently, developers should do the following actions in all existing kickstarts:

• Replace all smack-rules references by sec-smack-rules

Migrating from config.xml to manifest.yml

The use of config.xml (old widget implementation) is still supported but is deprecated in arz-1.1-update.

Starting from arz-1.1-update we recommend to use the new model based on a manifest (.rpconfig/manifest.yml file).

Developer can follow migration instructions to convert any existing config.xml to manifest.yml.

The documentation of manifest.yml files is available here.

From the redpesk OS point of view, a redpesk’s application should be installed in a subdirectory of AFM_APP_DIR, generally the subdirectory has the name of the application: AFM_APP_DIR/APPLICATION_NAME. This is what we can name ROOT_APP_DIR. But these is convention and is not enforced by the new framework.

For the current version of arz-1.1-update, the name of the RPM is important and is checked during the installation. So if the RPM is named NAME-VERSION-ETC.rpm, the framework detects that the installation is for a redpesk application only if it finds one of the below files, where PREFIX stands for any prefix directory:

• PREFIX/NAME/.rpconfig/manifest.yml, or,
• PREFIX/NAME/config.xml (legacy)

If a such file is found, the RPM is for a redpesk application and the installer install files with right security labels according to the manifest file and creates the configuration files for the application: launcher, api export and import, automatic start, …

In manifest.yml relative paths are relatives to the directory PREFIX/NAME.

Migration checklist

Here is the minimal check list when migrating from arz-1.0.x to arz-1.1.1 or later.

• Check CMakeList.txt files to be sure that CMAKE_INSTALL_PREFIX is correctly used. If afb-cmake-module is used correctly, there should be nothing to do. Use AFM_APP_DIR where needed.

• Check CMakeList.txt file to be sure that no linker script is set for bindings.

• Check the SPEC file to replace %_afmdatadir by %_afmappdir, and, /var/local/lib/afm/applications by %_afmappdir.

• When not using afb-cmake-modules, add a line set(AFM_APP_DIR ${CMAKE_INSTALL_PREFIX}/redpesk CACHE PATH "default install directory") and use AFM_APP_DIR where required.

Identification of versions

Package’s versions that includes and provides above changes are :

Package name	Version
afb-app-manager	>= 12.0.5
afb-binder	>= 5.0.2
afb-binding	>= 4.1.3
afb-client	>= 4.0.2
afb-cmake-modules	>= 10.0.6
afb-idl	>= 0.3.1
afb-libafb	>= 5.0.6
afm-rpm-macros	>= 2.2.0
rp-lib-utils	>= 0.0.5
sec-cynagora	>= 2.2.3
sec-lsm-manager	>= 2.3.0
sec-smack-rules (NEW)	>= 0.1.1