Development setup

This is the setup for working on BlockchainBench from source. Everything the workspace needs — Palladio, the 3SIM features, the standalone-initialisation libraries and JavaFX — comes from a single target platform definition that is checked into the repository.

Which route is right for you?

This route is aimed at development: extending the tool, changing the simulator bridge, or working on the models. If you only want to run simulations, use the packaged build — see Getting started.

Prerequisites

• Eclipse 2025-06 RAP
• Java 21 or newer (the bundles declare JavaSE-21)

Nothing else has to be installed by hand. In particular, JavaFX no longer needs an SDK download, e(fx)clipse, or a user library on the build path — the target platform provides it as OSGi bundles, one set per platform.

Setting up the workspace

1. Import the blockchainbench folder with all its projects into Eclipse.

2. Open releng/org.blockchainbench.target/org.blockchainbench.target.

3. Click Set as Active Target Platform in the top-right corner of the editor and wait for it to resolve. This takes a few minutes on first use: p2 downloads Palladio, the mdsd libraries, the Eclipse platform and the 3SIM features.

If hundreds of errors appear

p2 resolves a target as a whole: a single unreachable location or a single missing unit makes the entire target fail, and then nothing resolves — including your own bundles. The symptom is misleading, because the errors show up as Access restriction: The type … is not API on ordinary project dependencies.

Check Window → Preferences → Plug-in Development → Target Platform first: the active entry must resolve without an error marker. Use Reload and read the message it reports.

However, the errors just described do not prevent the program from executing. We therefore decided to configure Eclipse so that this type of error is treated as a warning rather than an error. Depending on the platform, you will need to consult the Eclipse documentation to find out how to configure this setting. This is a local setting.

Building

The bundles declare JavaSE-21, so the build needs Java 21 or newer. With an older JDK it fails early with Unknown OSGi execution environment: 'JavaSE-21'.

cd blockchainbench
mvn clean verify

This produces the p2 update site under releng/org.blockchainbench.updatesite/target/ and, from BlockchainBench.product, one archive per platform under .../target/products/ — Windows, Linux, macOS ARM and macOS Intel.

The same build runs in CI on every merge to main and publishes the archives as a release; the download links point at that release.

Example data

The repository ships example data under blockchainbench/example_data/:

Folder	Contents
base_configs/	the base configuration shared by all runs of a group
simulation_configs/	CSV files, one row per simulation run
models/	the blockchain system models, one folder per config_id
archive_v1/	the earlier, archived configuration set

The packaged product bundles a small subset of this as its data/ folder, so a fresh download can run without any further setup.

Changing the parameter configuration

The models are generated from the CSV, so the two never drift apart. When the set of parameters changes:

1. Edit the CSV in example_data/simulation_configs/.

2. Regenerate the models:

   python3 tools/generate_testmodels.py \
       example_data/simulation_configs/<your>.csv \
       example_data/models

   The generator refuses configurations it cannot represent, rather than producing models that silently simulate into degenerate results.

3. Check the outcome of a run with tools/check_results.py, which flags metrics that came out zero across the rounds.

See tools/README.md in the repository for the parameter semantics, units and the feasibility rules the generator enforces.