Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/eclipse-4diac/4diac-fbe

Build and cross-compilation environment for 4diac FORTE.
https://github.com/eclipse-4diac/4diac-fbe

4diac 4diac-forte build-system cross-compilation distributed-automation eclipse-4diac embedded-systems iec-61499 industrial-automation runtime

Last synced: 2 months ago
JSON representation

Build and cross-compilation environment for 4diac FORTE.

Awesome Lists containing this project

README 

          
4diac FORTE Build System (4diac-fbe)

==========================================================



[![Build Status](https://ci.eclipse.org/4diac/job/FORTE_DEVELOP_via_FBE/lastCompletedBuild/badge/icon?style=flat-square&subject=4diac%20FORTE%20on%20develop%20branch)](https://ci.eclipse.org/4diac/job/FORTE_DEVELOP_via_FBE/lastCompletedBuild/)



This repository contains a build environment for building 4diac FORTE, the

run-time engine of the 4diac IEC 61499 implementation.  Part of its workflow

is code generation and recompilation of 4diac FORTE, and this environment provides

the means to do this with as little effort as possible.



Furthermore, you can manage multiple builds for multiple target platforms.  As

of this writing, it works on Linux and Windows hosts.  There should be no

fundamental issues getting this to work on macOS, but no one did so.  Supported

targets are Linux (x86, ARM, MIPS, …) and Windows as well; again macOS should be

easy to add, others might need some more work.



Cross-compilation is built-in: you can generate binaries for all supported

platforms on a single build host.



The 4diac FORTE executable built by this build environment will have all optional

features enabled: OPC-UA, MQTT, modbus, and with an extra setup step also

openPOWERLINK.  It does not enable platform-specific features like OPC (no -UA)

by default, but different builds can have different target-specific

configuration options.



All resulting executables will be statically linked, so there is nothing to

deploy beyond the actual executable file, and it will not depend on any system

packages/features.  Exception: Windows targets will depend on system DLLs that

probably come with Windows since XP, maybe even earlier.  Full-featured

executable size is around 4MB, this varies slightly across targets.



Installation

============



The easiest way to install 4diac-fbe is through an official release: Check out

the `release` branch of `4diac-fbe` including all subrepositories, e.g. using

the `--recursive` flag of the git command line client. That's all.



IMPORTANT NOTE for Windows users: By default, Windows has a rather short file

name length limit.  It is therefore recommended to use an installation

directory close to the root of your drive, like `D:\4diac-fbe`. Also, avoid

a path containing whitespace.



The first time you run the compile script, the build environment will be set

up by securely downloading and installing a binary release of

`4diac-toolchains`.  If cross-compiling 4diac FORTE for a new target for the

first time, the build environment will download an appropriate cross-compiler

from the current `4diac-toolchains` release.



Updating

--------



If you run this from the git `release` branch, simply update the repo and all

subrepositories in place. In case there were significant toolchain updates,

run `toolchains/etc/bootstrap/clean.sh` to trigger downloading a new

toolchain release.



Usage

=====



Compiling a runtime executable

------------------------------



Builds are executed by `./compile.cmd`.  This is both, a Linux/Mac shell

script and a valid Windows batch file.  It allows single-doubleclick-builds

with no console interaction on Windows. If run in this way, all configurations

are built (see below). The final binaries will be created at

`build//output/bin`.



By default, all build output is recorded in one log file per package and the

console just displays a concise progress report. Log files are located in

`build//forte.log` and `build//cget/build/*.log`.

If you want a detailed output of all activities, pass `-v` to `compile.cmd`

and you will get verbose build output instead of log files.



In order to start over, `./clean.cmd` allows quick resetting of your build

output. If run without arguments, it will trigger rebuilding all 4diac FORTE

binaries but not their dependencies. Use the `--all` flag to also rebuild

dependencies. Pass a single config name to just rebuild that config. Note that

if a rebuild fails without `clean.cmd` but succeeds with it, that is considered

a bug: there should never be a reason to clean build output, consider reporting

this as a bug.



In order to override which 4diac FORTE version is built, you can just clone the

git branch/commit of your choice into subdirectory `4diac-forte`. This will

override the shipped version. Some provision is made to be compatible with

various versions (release, freeze, develop), but there may be compile errors

with unusual versions. Feel free to ask for help in that case.



You can also build executables outside the `4diac-fbe` directory.  In your

desired target directory, create a subdirectory `configurations` just like

the one in `4diac-fbe` and call `compile.cmd` with your target directory as the

current working directory. This will create the `build` directory in this

location instead of the `4diac-fbe` directory, allowing you to reuse a single

4diac-fbe installation for multiple projects. If you want to use a custom

4diac-forte source tree or custom dependencies, you can add `4diac-forte` and

`dependencies` subdirectories as needed, which will override the default code

shipped with 4diac-fbe.



Configuration management

------------------------



By default, the build script will build 4diac FORTE for all configurations present in

subdirectory `configurations`.  Every time the script is called, it will

update all builds with the exact same configuration.  The resulting executables

are located in subdirectory `build//output`.



You may customize builds by copying and modifying the template configuration

file `configurations/inc/config-template.txt` to the parent directory

`configurations`. By default, all configurations present in there will be

built. To temporarily disable a configuration, rename it so that it does not

end in `.txt` anymore.



If you want to build just a single configuration, specify its base name on the

command line.  Example: `./compile.cmd native-toolchain` only builds the

default version configured through `configurations/native-toolchain.txt`.



In order to manage complex sets of configurations, you can organize them in

subdirectories. Configurations in a subdirectory will not be built by default.

To process an entire subdirectory instead of the default set of configurations,

specify its name on the command line, e.g. `./compile.cmd configurations/test`.

Note that configuration names must still be unique, even when separated into

different directories (i.e. no two files with the same name in different

configuration directories).



Look at the template `configurations/inc/config-template.txt` for a thorough

configuration example. Usually, you won't need many options. Subdirectory

`configurations/tests` should be useful as further examples.



Cross Compilation

-----------------



You can select a cross-compiled build by setting `ARCH` in the build

configuration file (see above).  If cross-compiling 4diac FORTE for a new

target architecture for the first time, the build environment will download

an appropriate cross-compiler from the current `4diac-toolchains` release.

See `toolchains/etc/crosscompilers.sha256` for a list of pre-built

crosscompilers for the current release.



Cross-compilers are based on a triple configuration. Take

**x86_64-linux-musl** as an example:



- The first part (**x86_64**) represents the CPU architecture.  

- The second part (**linux**) specifies the operating system.  

- The third part (**musl**) specifies the calling convention, which might

  also involve hardware specific details.



The most popular targets are:



- **Windows:** `x86_64-w64-mingw32`

- **Linux:** `x86_64-linux-musl`

- **macOS:** `aarch64-apple-darwin20.2`  

- **Raspberry Pi:** (recent 64-bit versions) `aarch64-linux-musl`



The full list of supported targets varies from release to release and between

host platforms. See file `toolchains/etc/crosscompilers.sha256` to check which

targets your release supports



Adding generated function blocks

--------------------------------



When designing new Basic Function Blocks, Composite Function Blocks or Service

Function Blocks, the runtime has to be re-compiled to include code generated by

4DIAC-IDE.  This is the original reason this build system was created.



To add your own blocks, place the code generated by 4DIAC-IDE into

a subdirectory below `modules`.



Note: Previous versions of FBE tried to do a three-way merge for edited files.

This feature has been discontinued in favour of new and upcoming features of

4diac IDE.



Adding custom 4diac FORTE modules

---------------------------------



If you write custom 4diac FORTE modules, also put them into their own

subdirectories below `modules`. You can configure a different external

modules directory by using the `FBE_EXTERNAL_MODULES_DIR`

configuration option.



You can place the type definition files for 4diac IDE into subdirectory

`types`. The idea is that you copy the contents of the `types` directory

into new 4diac IDE projects to get access to all custom modules.



The git repository has been set up to ignore all modules by default. If you

want to add modules to a local branch or fork, put the following `.gitignore`

file into your module directory:



``

!*

``



That way you can selectively manage modules in subrepos or local branches and

leave other modules unmanaged as needed.



Adding external code

--------------------



If your code has additional dependencies, put them as `cget` recipes into

subdirectory `dependencies/recipes`, then add the package name to the `DEPS`

setting in the build configuration file (see above). In the configuration file,

you can also add any additional CMake settings required for your code, for

example additional compiler flags in `EXTRA_COMPILER_FLAGS` or additional

dependency packages in `DEPS`. See `configurations/native-toolchain.txt`

for some common examples.



For well-known external libraries, you might find `cget` recipes at

https://github.com/pfultz2/cget-recipes/tree/master/recipes/ -- but be aware

that some of these will need manual adaptions for static linking.



If you have to use pre-built external libraries (e.g. due to proprietary code or

huge external packages that take a lot of effort to build), you will need a

toolchain based on the GNU C library instead of the default MUSL-based

toolchains. These contain `-gnu` in their name and support dynamic linking,

but the drawback is more complicated distribution. The build system tries to

create a self-contained `bin` directory containing all dependency files, but

the result still might not be sufficient to run on a different system. This

depends on many details, you have been warned. Avoid it if you can.



Debugging Compile Problems

--------------------------



If you have unexplainable compiler errors or missing include files or things

like that, you can use the option `./compile.cmd -d ...` to force the build to

be single-threaded and output the individual compiler command lines. This helps

you to get more readable error output and check that all appropriate search paths

and compiler options have been set. NOTE: you must `clean.cmd` the build directory

every time you switch between verbose builds and normal builds.