Tutorial 2 Workspace

← 1. Install the dev environment · Tutorial index · 3. Your first application →

---

Chapter 2 — Start a new workspace

You never edit Theia's own source tree. Instead you scaffold a consuming workspace — your own git repo, bound to the installed framework, where you author .art, write C++, and deploy. This is the catkin / colcon analogue.

2.1 Create and bind the workspace

mkdir ~/my_ws && cd ~/my_ws
source /opt/theia/setup.sh        # if not already in your shell profile
theia init                        # scaffold THIS dir as a Theia workspace

theia init (with no args) scaffolds a bare workspace: the supervisor + your own apps, no ARA services. If your app will use the ARA services (com / log / per / sm / ucm / shwa), add them up front:

theia init --with-services

theia init is idempotent — re-run it any time (e.g. to add --with-services later). It never overwrites your files.

2.2 What theia init creates

In your workspace directory:

my_ws/
  system/
    system.art               the workspace aggregator (resolves everything)
    apps/
      package.art            YOUR app package — system.apps (empty to start)
      component.art          YOUR compositions + cluster (empty to start)
    platform/runtime              ─┐
    supervisor                     ├─ relative SYMLINKS into $THEIA_ROOT (not copied)
    services (if --with-services) ─┘
  apps/                      home for the generated C++ (gen-app --out apps)
  proto/                     home for the generated proto (gen-app --proto-out proto)
  manifest/
    bootstrap/rig.py         a one-machine smoke-test rig
  MODULE.bazel               a stripped Theia bazel module (binds @pero_theia)
  .bazelrc  .bazelversion
  .theia                     records the bound THEIA_ROOT

Two things to understand:

• system/apps/ is YOUR canonical app source. Package system.apps. You author here. It maps 1:1 from the fully-qualified name — there is no apps/system/apps indirection.
• Theia is not vendored. system/platform/runtime, system/supervisor (and, with --with-services, system/services) are relative symlinks into $THEIA_ROOT. Upgrading Theia is a re-source, not a re-copy.

2.3 How theia resolves "yours" vs "the framework"

When you run theia/bazel in the workspace, the toolchain splits the work:

• WORKSPACE = where you ran the command (your repo).
• THEIA_ROOT = the installed framework (/opt/theia).
• Bazel labels under //platform/… and //services/… build in THEIA_ROOT; your //apps/… build in your WORKSPACE against @pero_theia (wired via local_path_override + alias shims in MODULE.bazel).

You don't manage any of this by hand — it's set up by theia init. Just know that //apps/... is yours and //services/... / //platform/... are the framework's.

2.4 The smoke test (optional, recommended)

theia init scaffolds manifest/bootstrap/rig.py — a one-machine rig you can run immediately to prove the toolchain works end to end on your box, even before you've written any app code:

# generate the bootstrap manifest, install the runtime layout locally, run it
theia manifest bootstrap
theia install bootstrap
theia start

theia install takes the same <target> as theia manifest — the manifest/<target>/rig.py dir name (bootstrap here).

theia start brings up the supervisor (and the services, if you initialized --with-services) on your local machine. In another terminal:

tdb apps          # the supervised process tree
tdb ps            # the flat Linux-ps view (PID/TID/name)

Stop it with Ctrl-C in the theia start terminal (a single batch shutdown of all workers).

If theia start complains that per can't find libetcd-cpp-api.so, your setup.sh wasn't sourced — it exports the LD_LIBRARY_PATH that points at the bundled lib. Re-source /opt/theia/setup.sh.

---

You now have: your own workspace, bound to the framework, with an empty system.apps package and a working bootstrap rig.

Next: Chapter 3 — Write your first application, where you fill system/apps/ with a real Functional Cluster.

---

← 1. Install the dev environment · Tutorial index · 3. Your first application →