Skip to content

docs(build): document SDK and VM build workflow - #443

Draft
VicMisael wants to merge 1 commit into
masterfrom
docs/build-workflow-refresh
Draft

docs(build): document SDK and VM build workflow#443
VicMisael wants to merge 1 commit into
masterfrom
docs/build-workflow-refresh

Conversation

@VicMisael

Copy link
Copy Markdown
Collaborator

Description

This PR adds a build guide for compiling the TotalCross SDK first and then
building the TotalCross VM and launcher.

The documentation was created while revisiting the project after several
years. It also provides a clearer onboarding path for new contributors,
including prerequisites, generated artifacts, platform-specific instructions,
and troubleshooting for common build failures.

Related Issue

Not applicable. This is a documentation-only improvement and does not
introduce a feature or fix a runtime bug.

Motivation and Context

The repository contains the required build configuration, but the complete
SDK-to-VM workflow was spread across Gradle files, CMake configuration,
platform-specific documentation, scripts, and CI workflows.

The new guide documents:

  • required build tools and dependencies;
  • why the SDK must be built before the VM;
  • how SDK and runtime TCZ files are generated;
  • how to build libtcvm and the native launcher;
  • how to assemble a runnable application directory;
  • Android and iOS build commands;
  • Gradle log locations and verbosity options; and
  • troubleshooting for JDK 21 and missing SDL2 dependencies.

This should make it easier for returning and first-time contributors to
understand and reproduce the build process.

Benefited Devices

  • Device: development workstations
  • OS: Linux and macOS; Android and iOS build instructions are also included

How Has This Been Tested?

This is a documentation-only change for TotalCross 7.2.2.

The instructions were checked against the current repository configuration,
including:

  • TotalCrossSDK/build.gradle;
  • TotalCrossVM/CMakeLists.txt;
  • Android Gradle configuration;
  • iOS build scripts;
  • GitHub Actions build workflows; and
  • SDK Gradle build logs.

The following documentation validations were run:

python3 scripts/validate-copyright-headers.sh --files BUILDING.md
git diff --check -- BUILDING.md

Both commands passed.

A full SDK, native VM, Android, and iOS build matrix was not run as part of
this documentation-only change. These builds require dependency downloads and
platform-specific toolchains.

Tested Devices

  • Device: development workstation
  • OS: Linux

No physical Android or iOS devices were used because this PR only changes
documentation.

Screenshots or Videos

Not applicable.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

1 participant