Description
This generator package provides example conanfiles to show the different possibilities of usage.
An user can choose the one which is best suited for an individual use case and can adapt the conanfile to his own needs.
The following conanfiles will be explained regarding their differences and their way to use them.
General - build the example projects
Option A: Installing from a Package Reference
conan create conanfile_example_1.py demo_adtf_project_example1/0.0.1@dw/testing
Once you have created a package from this example, you can use it in any environment. Simply navigate to an empty directory and run the installation command. All the required configuration files, environment definitions, and start scripts will be generated automatically into that folder.
Note: You must include -g ADTF3Generator as the generator setting to trigger the ADTF-specific generation logic.
conan install demo_adtf_project_example1/0.0.1@dw/testing -g ADTF3Generator
Option B: Calling Directly on the Recipe (Local Development)
If you are still developing your project and want to test the generation logic without exporting to the Conan cache first, you can call conan install directly on the local directory containing your conanfile.py.
# Navigate to your recipe directory and run:
conan install source/examples/recipes/conanfile_example_1.py -g ADTF3Generator
Option C: Self-Contained Portable Deployment (Pro-Tip)
If you need to deploy your ADTF project to a target machine that does not have Conan installed (e.g., a test bench, a vehicle PC, or a restricted CI runner), use the self-contained generator.
# Generate a fully portable folder with relative paths
conan install source/examples/recipes/conanfile_example_1.py -g ADTF3GeneratorSelfContained
Why choose Option C?
- Zero Dependencies: The target machine doesn't need Conan or access to your Conan server.
- Portability: You can move, zip, or copy the resulting folder anywhere on the hard drive.
- Isolation: All required binaries (ADTF, CE, and your own plugins) are copied into a local
./dependencies subfolder, ensuring the versioning remains exactly as it was during generation.
Example 1 - Minimal recipe
The simplest way to use the ADTF3Generator is with a standard Conan recipe that defines your requirements.
The generator automatically inspects all dependent packages for .adtfenvironment files at the top level—a standard inclusion for all ADTF-based products. It then merges these into a single, comprehensive main.adtfenvironment file. This generated environment file acts as a central registry, informing ADTF products exactly which toolboxes and versions are available in the current dependency graph.
To streamline your workflow, the generator also produces a Configuration Editor startup script. This script automatically initializes the ADTF Configuration Editor with the generated environment file pre-loaded, ensuring all dependencies are resolved.
from conans import __version__ as ConanVersion
from conans.model.version import Version
if ConanVersion < Version("1.19"):
raise Exception("Conan client version 1.19 or higher required to use this Generator")
from conans import ConanFile
class DemoAdtfProjectExample1(ConanFile):
name = "demo_adtf_project_example1"
version = "0.0.1"
settings = "os", "compiler", "build_type", "arch"
requires = (
"adtf_conan_generator/2.2.0@dw/stable",
"adtf/3.25.0@dw/stable",
"adtf_qt5/1.3.4@dw/stable",
"adtf_configuration_editor/2.3.0@dw/stable"
)
Example 1 - Minimal recipe
The environment Configuration Section
The environment section within the adtf_generator dictionary is the primary way to override or extend standard environment generation. It maps directly to the ADTF environment specification.
This section for example allows you to:
- Define Macros: Use
"environment_directory_macro": "YOUR_MACRO_NAME". This creates a reusable variable within ADTF, ensuring project portability by avoiding hardcoded absolute paths.
- Inject Metadata: Directly adds
version, description, and documentation strings into the environment file headers for better traceability.
- Project Linkage: Defines which
.adtfproject files are associated with this environment. The generator automatically parses these projects to create corresponding session startup scripts.
- Tool Integration: Allows the definition of tools. If these tools are allowlisted, the generator creates executable scripts (e.g.,
.bat or .sh) to run them within the resolved environment. If you need to trigger a custom python script, a specialized debugger, or a specific ADTF utility, you add them to the tools array.
Why adtf_generator is in package_info
In Conan, the package_info() method is the "business card" of a package. When another project depends on this one, it reads package_info() to know which libraries to link or which environment variables to set.
- The Export: By setting
self.user_info.adtf_generator = self.adtf_generator, you are "exporting" that big dictionary of settings.
- The Consumer: When a developer runs
conan install, the ADTF Conan Generator (the tool listed in your requirements) looks for this specific user_info variable.
- The Result: It uses that data to automatically create the
.adtfenvironment and launch files on the user's disk. Without putting it in package_info, the information stays "trapped" inside the recipe and the ADTF3Generator not know how to configure itself.
The Allowlists: Filtering the Tools & Sessions
In a complex ADTF setup, you often have multiple dependencies (requirements) that each bring their own .adtfenvironment files and launch tools.
- The Problem: Without a allowlist, the Conan generator will scan all referenced environment files from every dependency and collect every single launch tool it finds.
- The Solution: Use
sessions_allowlist and tools_allowlist as a filter.
Conanfile
from os.path import join
from conans import __version__ as ConanVersion
from conans.model.version import Version
if ConanVersion < Version("1.19"):
raise Exception("Conan client version 1.19 or higher required to use this Generator")
from conans import ConanFile
import os
class AdtfConanFileExample2(ConanFile):
name = "demo_adtf_project_example2"
version = "0.0.1"
settings = "os", "compiler", "build_type", "arch"
requires = (
"adtf_conan_generator/2.2.0@dw/stable",
"adtf/3.25.0@dw/stable",
"adtf_qt5/1.3.4@dw/stable",
"adtf_configuration_editor/2.3.0@dw/stable"
)
scm = {
"type": "git",
"url": "auto",
"revision": "auto",
}
script_dir = os.path.dirname(os.path.realpath(__file__))
adtf_generator = {
"name": name,
"base_path": os.path.join(script_dir, "..", "projects", "demo_adtf_project_base"),
"target_path": ".",
"sessions_allowlist": ["demo_adtf_session"],
"tools_allowlist": ["Example Launch"],
"environment": {
"version": version,
"description": "ADTF Conan Generator Example Project.",
"environment_directory_macro": "EXAMPLE_PROJECT_DIR",
"projects": [
"demo_adtf_project_base.adtfproject"
],
"tools": [
{
"name": "Example Launch",
"type": "launch",
"command": '"$(ADTF_DIR)/bin/adtf_launcher" --environment "$(ADTF_ENVIRONMENT_FILENAME)" --session "$(ADTF_SESSION_FILENAME)" --console --run --control-url "$(ADTF_REMOTE_CONTROL_URL)" --quit-timeout 3',
"requires_shell": True,
"working_directory": "$(ADTF_DIR)/bin",
"shortcut": "",
"icon_path": "$(ADTF_DIR)/settings/Launcher.svg"
}
]
}
}
def package(self):
self.copy("*.*",
src=os.path.join(self.source_folder, "examples", "projects", "demo_adtf_project_base"), dst="demo_adtf_project_base")
self.copy("examples.md",
src=os.path.join(self.source_folder, "examples"), dst="doc")
self.copy("conanfile_example_2.py",
src=os.path.join(self.source_folder, "examples", "recipes"), dst=os.path.join(self.package_folder, "examples"))
def package_info(self):
self.adtf_generator["base_path"] = os.path.join(self.package_folder, "demo_adtf_project_base")
self.user_info.adtf_generator = self.adtf_generator
def package_id(self):
self.info.header_only()
Example 3 - CE Settings and Macros
Configuration Editor Customization (ce_settings)
Example 3 introduces the ce_settings block, which allows you to programmatically control the behavior of the ADTF Configuration Editor (CE).
- Remote Management: It enables
remote_settings and pre-configures a list of remote URLs (e.g., http://localhost:8001).
- Benefit: When a developer opens the project, the Configuration Editor is already "tuned" to the project's specific network environment.
Extended Metadata & Macros
Example 3 moves beyond basic descriptions to provide a fully documented environment:
- Documentation Linkage: The
"documentation" key maps specific titles to Markdown or HTML files (e.g., "doc/examples.md"). These links appear within the ADTF GUI to assist users.
- Custom Macros: The
"macros" dictionary (e.g., "MY_MACRO": "VALUE") allows you to define arbitrary key-value pairs that become available as $(MY_MACRO) throughout the ADTF session.
Conanfile
from os.path import join
from conans import __version__ as ConanVersion
from conans.model.version import Version
if ConanVersion < Version("1.19"):
raise Exception("Conan client version 1.19 or higher required to use this Generator")
from conans import ConanFile
import os
class AdtfConanFileExample3(ConanFile):
name = "demo_adtf_project_example3"
version = "0.0.1"
settings = "os", "compiler", "build_type", "arch"
requires = (
"adtf_conan_generator/2.2.0@dw/stable",
"adtf/3.25.0@dw/stable",
"adtf_qt5/1.3.4@dw/stable",
"adtf_configuration_editor/2.3.0@dw/stable"
)
scm = {
"type": "git",
"url": "auto",
"revision": "auto",
}
script_dir = os.path.dirname(os.path.realpath(__file__))
adtf_generator = {
"name": name,
"base_path": os.path.join(script_dir, "..", "projects", "demo_adtf_project_base"),
"environment": {
"version": version,
"description": "ADTF Conan Generator Example Project.",
"environment_directory_macro": "EXAMPLE_PROJECT_DIR",
"plugin_directories": [
"bin"
],
"documentation": {
"demo adtf conan generator example project documentation": "doc/examples.md"
},
"tools": [
{
"name": "Print ADTF Remote Control URL",
"type": "external",
"command": "--url $(adtf_remote_control_url)",
"requires_shell": True,
"working_directory": "",
"shortcut": "Ctrl+Alt+U",
"icon_path": ""
}
],
"macros": {
"MY_MACRO": "VALUE"
},
"projects": [
"demo_adtf_project_base.adtfproject"
]
},
"ce_settings": {
"remote_settings": {
"enabled": True,
"fep_discovery": True,
"remotes": [
{"url": "http://localhost:8001"},
{"url": "http://localhost:8002"}
]
}
}
}
def package(self):
self.copy("*.*",
src=os.path.join(self.source_folder, "examples", "projects", "demo_adtf_project_base"), dst="demo_adtf_project_base")
self.copy("examples.md",
src=os.path.join(self.source_folder, "examples"), dst="doc")
self.copy("conanfile_example_2.py",
src=os.path.join(self.source_folder, "examples", "recipes"), dst=os.path.join(self.package_folder, "examples"))
def package_info(self):
self.adtf_generator["base_path"] = os.path.join(self.package_folder, "demo_adtf_project_base")
self.user_info.adtf_generator = self.adtf_generator
def package_id(self):
self.info.header_only()
Example 4 - Generate Launch Scripts Only (without CE)
Comparable to Example 1, but without Configuration Editor. Only the start scripts for the launch tools are created for the sessions of the specified project.
Conanfile
from conans import __version__ as ConanVersion
from conans.model.version import Version
if ConanVersion < Version("1.19"):
raise Exception("Conan client version 1.19 or higher required to use this Generator")
from conans import ConanFile
import os
class AdtfConanFileExample1(ConanFile):
name = "demo_adtf_project_example4"
version = "0.0.1"
settings = "os", "compiler", "build_type", "arch"
requires = (
"adtf_conan_generator/2.2.0@dw/stable",
"adtf/3.25.0@dw/stable"
)
adtf_generator = {
"base_path": os.path.join(os.path.dirname(os.path.realpath(__file__)), "..", "projects", "demo_adtf_project_base"),
"environment": {
"projects": [
"demo_adtf_project_base.adtfproject"
]
}
}
scm = {
"type": "git",
"url": "auto",
"revision": "auto",
}
def package(self):
self.copy("*.*", src=os.path.join(self.source_folder, "examples", "projects", "demo_adtf_project_base"), dst="demo_adtf_project_base")
def package_info(self):
self.adtf_generator["base_path"] = os.path.join(self.package_folder, "demo_adtf_project_base")
self.user_info.adtf_generator = self.adtf_generator
