ADTF3 Guides - Set up an adtfenvironment

Set up an adtfenvironment

This guide covers the handling of *.adtfenvironment files to integrate spreaded components, using predefined macros for generic solutions and how to customize base packages and own products.

Motivation

In an ADTF universe comparable to Utopia each machine running ADTF looks exactly the same so everything will work out of the box. Reading this sentence already makes clear, that it is impossible to guarantee that an ADTF Session designed on Computer A will run on Computer B without any issues - even on different platforms. But this is exactly what ADTF is about (or better should be).

What we (and of course you) might remember from ADTF 2.x, there is an $(ADTF_DIR)/addons folder within ADTF and the default configuration will load the binaries and required information from there. If this is the base setup on each machine (including same naming conventions), everything will work - in Utopia

But already in the world of ADTF 2.x, ADTF users store their components on different paths and telling ADTF in easy or complex ways where everything can be found. This works as long as everybody knows what to do and even more where.

Besides major differences in architecture the process in ADTF 3.x works almost the same but you can define environment variables which will be used by ADTF Configuration Editor to specify the paths to your adtfplugin, stored within the ADTF System as part of the ADTF Session and resolved by ADTF Launcher to launch the ADTF Session and make the execution possible. The main problem is that the scope of these environment variables is only within the ADTF System and must be set for each ADTF Session. Furthermore, it must be configured from outside because (we already know) file systems may differ. But users should not change their workflows, defining environment variables from outside or created symlinks to getting confuse in larger setups.

So what we need is an easier way to provide these information and let the ADTF Session still be generic for each machine, platform and version - customization must be done by the user for the specific machine setup. The solution must be (re)usable to design ADTF Sessions as well as launching them.

Description

Starting with ADTF 3.9.0 it will be possible to load *.adtfenvironment files in ADTF Configuration Editor and ADTF Launcher / ADTF Control / ADTF GUI Control).

With these *.adtfenvironment files a package of a single component or also a bundle of adtfplugins (e.g. Toolboxes) can provide additional information about version, platform, locations of binaries, documentation and custom macros. Furthermore you can define a macro which points to your root directory thus the tools within ADTF can access and use these information by referencing relative to the provided root directory macro (see node <environment_directory_macro>).

*.adtfenvironment files can also include other *.adtfenvironment files, so they will be referenced within the main *.adtfenvironment file (default $(ADTF_DIR)/adtf.adtfenvironment).

Common Usage

An *.adtfenvironment file is placed at the top-level of each package and describes its content ("environment"), as you can see inside the given paths are relative to it. By defining a macro for this root section, everything will be resolved to this path afterwards.

For details about the layout please have a look at the ADTF Environment XML Schema file.

The default *.adtfenvironment ($(ADTF_DIR)/adtf.adtfenvironment) includes all *.adtfenvironment files from the $(ADTF_DIR)/addons folder following $(ADTF_DIR)/addons/*/*.adtfenvironment wildcard structure. This makes all components of the toolboxes places in $(ADTF_DIR)/addons folder available and providing the root macro of each package.

Including additional documentation

Another part of the *.adtfenvironment files is the documentation of the included packages which will be available at Home view of ADTF Configuration Editor:

Customize base adtfenvironment

For launching the ADTF Session the call for the runtime tool (ADTF Launcher, ADTF Control, ADTF GUI Control) can be extended by argument --environment <adtfenvironmentfile> (if not specified, $(ADTF_DIR)/adtf.adtfenvironment is used as default).

Within the ADTF Configuration Editor the loaded *.adtfenvironment file is availabe as macro ADTF_ENVIRONMENT_FILENAME. This makes it possible to use within launch options and set as value for the argument. We already prefilled the default launch options with that:

This is necessary if you are using a custom *.adtfenvironment file and starting the ADTF Configuration Editor with it - using argument --environment <adtfenvironmentfile> for calling the executable or switching within Settings Editor (Options):

A custom *.adtfenvironment file usually includes the common $(ADTF_DIR)/adtf.adtfenvironment (which includes its default includes from $(ADTF_DIR)/addons folder). Example:

        
<?xml version="1.0" encoding="utf-8"?>
<environment_file  xmlns="adtf/xsd/environment">
    <file_version>
        <major>1</major>
        <minor>0</minor>
    </file_version>
    <name>tbd</name>
    <version>tbd</version>
    <platform>tbd</platform> <!-- windows_x86_64 | linux_x86_64 | linux_aarch64 --> 
    <description/>
    <environment_directory_macro>tbd</environment_directory_macro>
    <includes>
        <include>
            <url>$(ADTF_DIR)/adtf.adtfenvironment</url>
        </include>
    </includes>
    <macros/>
    <plugin_directories/>
    <ce_plugin_directories/>
    <documentation/>
    <adtf_file_plugins/>
</environment_file>

In this example the custom environment includes ADTF which also includes the ADTF Device Toolbox, because its part of the $(ADTF_DIR)/addons folder.

As you might remember, we are trying to arrange an environment which components are spread. This means we have to adapt the custom *.adtfenvironment file and locate our packages, so let's extend the example with the ADTF Calibration Toolbox from our conan cache:

If you a running an automatic setup (like conan or any other helper), you can generate a customized *.adtfenvironment file which sets your dependency and can be loaded with the toolset of ADTF.

Now we have a solution for adtfplugins from ADTF itself, also the containing packages in $(ADTF_DIR)/addons folder and additonal packages from anywhere. The Session Designer can now set up a generic solution, the only thing a User from a different machine has to do is adapting a custom *.adtfenvironment file and set the paths for his or her setup (or as you might understand now just use everything from default if part of $(ADTF_DIR)/addons folder).

The used *.adtfenvironment file will be stored within the used *.cesettings file. As you might know, the default used *.cesettings file is located in your HOME directory. In case you are calling the ADTF Configuration Editor using argument --settings <cesettingsfile> for customized settings, the used *.adtfenvironment file will follow this rule and will be save there.

Specifing an adtfenvironment for own products

Of course you will doing the same and place an *.adtfenvironment file on the root folder of your custom products. For creation help please use the template or call the CMake function adtf_create_environment provided by ADTF ($(ADTF_DIR)/ADTFMacros.cmake), for example:

        
adtf_create_environment(
    NAME "MY_OWN_PRODUCT"
    VERSION "${MY_OWN_PRODUCT_VERSION}"
    DESCRIPTION "My Own Product Environment"
    DIRECTORY_MACRO "MY_OWN_PRODUCT_DIR"
    INCLUDES "path/to/optional/includes/*.adtfenvironment"
    PLUGIN_DIRECTORIES
        "bin"
        "bin/debug"
    CE_PLUGIN_DIRECTORIES
        "bin"
    ADTF_FILE_PLUGINS_RELEASE
        "bin/my_exporter.adtffileplugin"
        "bin/my_reader.adtffileplugin"
    ADTF_FILE_PLUGINS_DEBUG
        "bin/my_exporterd.adtffileplugin"
        "bin/my_readerd.adtffileplugin"
    DOCUMENTS
        "Some documentation" "doc/some_documentation.html"
        "Even more" "doc/even_more.html"
    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/my_own_product.adtfenvironment
)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/my_own_product.adtfenvironment DESTINATION .)

The <platform> node information will be set automatically according to the build machine.

Where to go next?

Have a look at the Configuration Editor guide to learn what's in an ADTF Session and how to set it up.