From d010374bda4e4d79ba9ec46126233093db7675de Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Thu, 16 Oct 2025 14:54:53 +0000 Subject: [PATCH] revised build envornment doc by Triskel --- ...s_environment.org => build_environmnt.org} | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) rename document/{developer_buils_environment.org => build_environmnt.org} (68%) diff --git a/document/developer_buils_environment.org b/document/build_environmnt.org similarity index 68% rename from document/developer_buils_environment.org rename to document/build_environmnt.org index a882618..4fb50c0 100644 --- a/document/developer_buils_environment.org +++ b/document/build_environmnt.org @@ -1,4 +1,4 @@ -#+TITLE: RT Harmony Build Environment (Orchestrator + Roles: lib_cli, kmod) +#+TITLE: RT Harmony Build Environment (Orchestrator + Build Domains: lib_cli, kmod) #+OPTIONS: toc:nil * 0. Scope @@ -6,35 +6,35 @@ A concise contract for building user-space artifacts (static libraries + CLI exe * 1. Core Principles 1.1 Minimize complexity (YAGNI). Prefer one happy path; add branches only when mandated. -1.2 Variable-driven config: the project declares *what* to build; role files define *how*. +1.2 Variable-driven config: the project declares *what* to build; domain makefiles define *how*. 1.3 Automatic discovery: detect work by suffix/patterns—~*.lib.c~, ~*.cli.c~, ~*.mod.c~—never hard-code basenames. 1.4 Authored sources are read-only to scripts; all synthesis happens in ~scratchpad/~. -1.5 Roles are independent and reusable; orchestration is done by separate ~make -f~ calls. +1.5 Build domains are independent and reusable; orchestration is done by separate ~make -f~ calls. -* 2. Repo Layout & Authority +* 2. Repo Layout, Authority, and Skeleton 2.1 =REPO_HOME= is exported by the environment and is the **authoritative project root**. Never recompute or override it in Makefiles. 2.2 Invoke the build from =$REPO_HOME/developer=. -2.3 Shared includes live under: +2.3 Domain makefiles are vendored under: =$(REPO_HOME)/tool_shared/third_party/RT-project-share/release/make/= - (project-vendored RT-project-share). 2.4 Directory semantics: - - =developer/cc/= **authored** C sources (read-only to scripts). - - =scratchpad/= **SCRATCHPAD** (intermediates, depfiles, kbuild outputs). Git-ignored. - - =machine/= released executables (version-controlled). Prefer arch suffix in names. + 2.4.1 =developer/cc/= **authored** C sources (read-only to scripts). + 2.4.2 =scratchpad/= **SCRATCHPAD** (intermediates, depfiles, kbuild outputs). Git-ignored. + 2.4.3 =machine/= released executables (version-controlled). Prefer arch suffix in names. +2.5 **Harmony skeleton invariants (pre-created directories):** The Harmony skeleton lays down the standard tree *before* any build runs (e.g., =developer/=, =developer/cc/=, =scratchpad/=, =machine/=, =release/make/=, =tool_shared/...=). Domain makefiles and recipes may assume these exist; =mkdir -p= in build rules is unnecessary unless a domain explicitly introduces new subtrees. -* 3. Roles & Files +* 3. Build Domains & Files 3.1 Orchestrator (project-local): =developer/tool/makefile= - Public targets: ~all~, ~lib_cli~, ~kmod~, ~clean~ (~usage~ optional; ~all~ is first). - - Includes =environment_RT_1.mk= and invokes role files via ~make -f~. -3.2 Role: user-space build → =target_lib_cli.mk= (shared; under RT-project-share) + - Includes =environment_RT_1.mk= and invokes domain makefiles via ~make -f~. +3.2 Domain: user-space build → =target_lib_cli.mk= (shared; under RT-project-share) - Builds static lib from ~*.lib.c~ and CLI executables from ~*.cli.c~. - Public targets: ~library~, ~cli~, ~clean~. ~cli~ depends on ~library~. -3.3 Role: kernel modules → =targets_kmod.mk= (shared; under RT-project-share) +3.3 Domain: kernel modules → =targets_kmod.mk= (shared; under RT-project-share) - Builds out-of-tree modules (.ko) from ~*.mod.c~ using Kbuild. - Public targets: ~kmod~, ~clean~. * 4. Public-Target Orchestration (strict) -4.1 The **orchestrator** owns public targets and their order. Roles expose callable, explicit targets but are not public entrypoints. +4.1 The **orchestrator** owns public targets and their order. Domain makefiles expose callable, explicit targets but are not public entrypoints. 4.2 Example (shape): #+BEGIN_SRC makefile # developer/tool/makefile — public surface @@ -54,14 +54,14 @@ clean: @$(MAKE) -f $(RT_INCOMMON)/make/target_lib_cli.mk clean @$(MAKE) -f $(RT_INCOMMON)/make/targets_kmod.mk clean #+END_SRC -4.3 Result: no target collisions (each role runs in its own ~make -f~). ~all~ remains the single happy path. +4.3 Result: no target collisions (each domain runs in its own ~make -f~). ~all~ remains the single happy path. * 5. Discovery & Suffix Contract 5.1 Suffixes define intent; scripts don’t embed filenames: - - ~*.lib.c~ → compiled into a static archive. - - ~*.cli.c~ → linked into CLI executables. - - ~*.mod.c~ → compiled by Kbuild into ~.ko~. -5.2 Discovery happens in the role files; the orchestrator can optionally export a filtered list (e.g., subset kmods), but roles must work without it. + 5.1.1 ~*.lib.c~ → compiled into a static archive. + 5.1.2 ~*.cli.c~ → linked into CLI executables. + 5.1.3 ~*.mod.c~ → compiled by Kbuild into ~.ko~. +5.2 Discovery happens in the domain makefiles; the orchestrator can optionally export a filtered list (e.g., subset kmods), but domains must work without it. * 6. Authored vs Write Areas (contract) 6.1 **Authored** (=developer/cc/= and other documented trees): tools do not write, delete, or generate within. @@ -69,7 +69,7 @@ clean: 6.3 **machine/**: released executables (checked in). If shared across hosts, embed arch in filename (e.g., ~prog-$(shell uname -m)~). “Machine-like” *temporary* outputs go to ~scratchpad/~, not ~machine/~. * 7. Dependencies -7.1 User-space role enables per-object depfiles: ~CFLAGS += -MMD -MP~; role includes ~$(OBJECT:%.o=%.d)~. +7.1 User-space domain enables per-object depfiles: ~CFLAGS += -MMD -MP~; domain includes ~$(OBJECT:%.o=%.d)~. 7.2 Depfiles live beside objects in ~scratchpad/~ and are removed by ~clean~. 7.3 No separate “make dependency” step is required; changes to headers or structure are picked up automatically. 7.4 Kbuild manages its own deps internally when invoked for kmods. @@ -108,27 +108,27 @@ clean: $(MAKE) -C $(KDIR) M=$(REPO_HOME) O=$(KBUILD_OUTPUT_DIR) obj-m="$(KERNEL_OBJS_M)" clean #+END_SRC -* 9. User-Space Role (lib + CLI) -9.1 Role name: =target_lib_cli.mk=. +* 9. User-Space Domain (lib + CLI) +9.1 Domain name: =target_lib_cli.mk=. 9.2 Pattern (shape): #+BEGIN_SRC makefile -# target_lib_cli.mk (shape only) +# target_lib_cli.mk (shape) # Scan *.lib.c / *.cli.c; derive OBJECT_LIB / OBJECT_EXEC under $(SCRATCHPAD) # -include $(OBJECT_LIB:.o=.d) $(OBJECT_EXEC:.o=.d) -# library target builds $(LIBFILE) from OBJECT_LIB (empty archive is OK) -# cli target depends on $(LIBFILE), then links each $(EXECDIR)/% from %.cli.o + $(LIBFILE) +# library: builds $(LIBFILE) from OBJECT_LIB (empty archive is OK) +# cli: depends on $(LIBFILE); links each $(EXECDIR)/% from %.cli.o + $(LIBFILE) #+END_SRC * 10. Variable Conventions 10.1 Only variables intended for export to sub-processes are ALL_CAPS (environment-style). 10.2 =REPO_HOME= is authoritative (exported by env); do not assign to it in Makefiles. -10.3 Use =SCRATCHPAD= (not TMPDIR) as the canonical name for the scratch directory in new code; keep a compatibility alias only if needed. +10.3 Use =SCRATCHPAD= (not TMPDIR) as the canonical name for the scratch directory in new code. 10.4 Prefer explicit paths to archives (e.g., link with ~$(LIBFILE)~) unless you intentionally maintain ~-L/-l~ naming. * 11. Usage & Defaults -11.1 Role files put ~usage~ as the first target (direct calls print help and exit non-zero). +11.1 Domain makefiles put ~usage~ as the first target (direct calls print help and exit non-zero). 11.2 Orchestrator keeps ~all~ as the first target (so ~make~ “just works”). -11.3 Skip-if-empty logic is *not required*: if no sources match, role targets naturally no-op (empty prereq lists). +11.3 Skip-if-empty logic is *not required*: if no sources match, domain targets naturally no-op (empty prereq lists). 11.4 Optional diagnostic: a ~check-pwd~ target in the orchestrator can warn if ~$(CURDIR) ≠ $(REPO_HOME)/developer~. * 12. Release Conventions (machine/) @@ -137,10 +137,10 @@ clean: 12.3 Temporary binaries or architecture-variant scratch builds go to ~scratchpad/~. * 13. Summary (Do / Don’t) -13.1 Do keep roles independent; orchestrator stitches them via ~make -f~. +13.1 Do keep domains independent; orchestrator stitches them via ~make -f~. 13.2 Do derive *what to build* from suffixes; don’t hard-code filenames. 13.3 Do confine writes to ~scratchpad/~ (and ~machine/~ for releases); never write in authored trees. 13.4 Do use ~-MMD -MP~ and include per-object depfiles; don’t require humans to rebuild deps. 13.5 Don’t recompute ~REPO_HOME~; don’t pass ~PWD~ unnecessarily; environment inheritance suffices. -13.6 Use clear names: public targets = ~lib_cli~, ~kmod~, ~clean~; role files = ~target_lib_cli.mk~, ~targets_kmod.mk~. - +13.6 Use clear names: public targets = ~lib_cli~, ~kmod~, ~clean~; domain files = ~target_lib_cli.mk~, ~targets_kmod.mk~. +13.7 Remember: Harmony **skeleton** pre-creates the standard tree; recipes may assume directories exist. -- 2.20.1