OS migration from arz-1.0 to arz-1.1-update
This document presents evolutions and differences between redpesk versions from arz-1.0.x to arz-1.1-update (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.
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
toTRUE
- does not modify
PROJECT_VERSION
,PROJECT_NAME
anymore, - does not redefine
CMAKE_INSTALL_PREFIX
,CMAKE_INSTALL_LIBDIR
,CMAKE_INSTALL_LIBEXECDIR
- set
-
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 splitted 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 bysec-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-update or later.
-
Check
CMakeList.txt
files to be sure thatCMAKE_INSTALL_PREFIX
is correctly used. If afb-cmake-module is used correctly, there should be nothing to do. UseAFM_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
.
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 |