From fb4878a86ef5563590ce63cbcb5097c1d5bb85e6 Mon Sep 17 00:00:00 2001 From: Maciej Kaszynski Date: Fri, 9 Oct 2026 09:23:05 +0100 Subject: [PATCH 1/2] Splitting glossary into detailed and feature level --- BUILD | 37 ++++- docs/features/lifecycle/glossary.rst | 151 ------------------ docs/features/lifecycle/glossary_detailed.rst | 60 +++++++ 3 files changed, 91 insertions(+), 157 deletions(-) delete mode 100644 docs/features/lifecycle/glossary.rst create mode 100644 docs/features/lifecycle/glossary_detailed.rst diff --git a/BUILD b/BUILD index d95cbdbd06..b539fee41c 100644 --- a/BUILD +++ b/BUILD @@ -12,7 +12,8 @@ # ******************************************************************************* load("@rules_python//python:pip.bzl", "compile_pip_requirements") -load("@score_docs_as_code//:docs.bzl", "docs") +load("@score_docs_as_code//:bzl/bundle_rules.bzl", "bundle_source_files") +load("@score_docs_as_code//:docs.bzl", "docs", "docs_bundle") load("@score_tooling//:defs.bzl", "copyright_checker", "dash_license_checker", "setup_starpls") load("@score_tooling//third_party/format:macros.bzl", "use_format_targets") load("//:project_config.bzl", "PROJECT_CONFIG") @@ -108,17 +109,41 @@ use_format_targets(languages = [ exports_files(["MODULE.bazel"]) # Docs +_IS_ROOT_MODULE = repository_name() == "@" + +bundle_source_files( + name = "platform_docs_sources", + bundle = "@score_platform//:docs_bundle", +) + +genrule( + name = "platform_glossary_rst", + srcs = [":platform_docs_sources"], + outs = ["platform_glossary/glossary.rst"], + cmd = "cp $$(printf '%s\\n' $(SRCS) | grep '/docs/features/lifecycle/glossary[.]rst$$') $@", +) + +docs_bundle( + name = "platform_glossary", + srcs = [":platform_glossary_rst"], + entry_doc = "glossary", +) + docs( bundles = [ - { - "bundle": "//score/launch_manager:docs", - "mount_at": "components/launch_manager", - }, { "bundle": "//score/health_monitor:docs", "mount_at": "components/health_monitor", }, - ], + ] + ([ + # Glossary is located in score_platform but we also need to + # avoid duplication during integration in ref_int repository + { + "attach_to": "features/lifecycle/index", + "bundle": ":platform_glossary", + "mount_at": "features/lifecycle", + }, + ] if _IS_ROOT_MODULE else []), external_needs = [ "@score_platform//:needs_json", # This allows linking to feature requirements. "@score_process_description//:needs_json", # This allows linking to requirements (wp__requirements_comp, etc.) from the process_description repository. diff --git a/docs/features/lifecycle/glossary.rst b/docs/features/lifecycle/glossary.rst deleted file mode 100644 index 906d4de6d3..0000000000 --- a/docs/features/lifecycle/glossary.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Glossary -======== - -.. glossary:: - Lifecycle Feature - Feature providing support for starting and stopping processes. - - Launch Manager - Component to start and stop processes on a POSIX like operating system. - - Health Monitor - Provides process local monitoring functionalities such as deadline monitoring - and logical program flow monitoring. - - Control Interface - Interface to control the lifecycle of the system, e.g. to start and stop processes. - - Alive Interface - Interface to monitor the aliveness of a process. - - Sandbox - A sandbox is a set of configurations, which are applied to a process when it - is started. It can include environment variables, secpol policies, cgroup - configurations, user and group IDs etc. - - Health Monitor Interface - Interface to monitor the health of a process, e.g. to check if a process is - alive or if it is running as expected. - - Lifecycle Interface - Interface to report :term:`readiness ` of a process to the - :term:`Launch Manager`. - - Alive Monitoring - Checks if an application reports an alive state in a certain period. - - Deadline Monitoring - Monitor to detect if a state was reached within a specified time related to - another event. - - Logical Programflow Monitoring - Monitor to detect if certain states were reached in a defined sequence and - time interval. - - Run State - An Run State defines a set of components, which are in status running - and are supervised by the software platform. If the health management system - detects abnormal situation it can change the :term:`Run State`. - - Component - A configurable unit in the Launch Manager that describes an executable and its runtime environment (sandbox). Components can be grouped together in Run Targets to define system operational states. - - Component failure - A state when the component has failed to reach its :term:`Ready Condition`, a running component has terminated abnormally or its supervision failed. - - Ready State - A state when the component has fulfilled its :term:`Ready Condition`, i.e. is ready to provide services to other components. - - Dependency (between components) - A configuration parameter indicating that **Component A** can only start - after **Component B** has reached its :term:`Ready State`. In this case, - **Component A** depends on **Component B**. - - Dependency (between Run Targets) - A configuration parameter indicating that **Run Target A** includes all - components from **Run Target B**. In this case, **Run Target A** depends - on **Run Target B**. - - Lifecycle Component - Node of the dependency tree. - - Process - Instantiation of an Executable programs running on the system that are managed by the Launch Manager. - - UID - User Identifier - a unique number assigned to each user on a Unix-like operating system. - - GID - Group Identifier - a unique number assigned to each group on a Unix-like operating system. - - Polling Interval - The time interval between successive checks of a condition or status. - - Working Directory - The current directory from which a process is executed, also known as CWD (Current Working Directory). - - File Descriptor - A handle used by a process to access files or other input/output resources. - - Procmgr - Process Manager - a QNX system component that manages process creation and execution. - - ASLR - Address Space Layout Randomization - a security technique that randomizes the memory layout of processes. - - Recovery Action - Actions taken by the Launch Manager as a response to a :term:`Component failure` or :term:`Run Target` activation failure. - - Ready Condition - A configurable condition that must be satisfied before a component is considered ready and operational. Ready conditions can include file system checks, network availability, or custom application-specific signals. - - Ready conditions can either be reported by the component itself through the Lifecycle Interface or determined via external state monitoring. External state examples include: process started, file is available, socket was opened, or that the process finished successfully. - - Liveliness - Term indicating that a :term:`Component` is periodically sending an alive notification (using the - :need:`logic_arc_int_op__lifecycle__report_alive` interface) as per configuration. - - Monitoring of Processes - The activity of observing and checking if a process is running or has been exited with an abnormal status. - - Watchdog - A monitoring mechanism that detects system failures and can trigger recovery actions. - - Interval - A period of time between events or measurements. - - QNX - A real-time operating system commonly used in embedded systems. - - - DSS - Device Safe State - a safe operational state that a system can enter during failures. - - DAG - Directed Acyclic Graph - a data structure used to represent dependencies between processes. - - SWC - Software Components - modular software units that can be independently managed. - - Run Target - A named collection of components and their dependencies that can be activated, stopped, or switched as a group to achieve a specific operational mode or configuration. - - Fallback Run Target - A designated Run Target that the system can switch to in case the current active Run Target resp. one of its components fails. - - Operating System - The system software that manages computer hardware and software resources and provides common services for computer programs. diff --git a/docs/features/lifecycle/glossary_detailed.rst b/docs/features/lifecycle/glossary_detailed.rst new file mode 100644 index 0000000000..131142fb12 --- /dev/null +++ b/docs/features/lifecycle/glossary_detailed.rst @@ -0,0 +1,60 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Glossary +======== + +.. glossary:: + Lifecycle Interface + Interface to report :term:`readiness ` of a process to the + :term:`Launch Manager`. + + Component failure + A state when the component has failed to reach its :term:`Ready Condition`, a running component has terminated abnormally or its supervision failed. + + UID + User Identifier - a unique number assigned to each user on a Unix-like operating system. + + GID + Group Identifier - a unique number assigned to each group on a Unix-like operating system. + + Working Directory + The current directory from which a process is executed, also known as CWD (Current Working Directory). + + File Descriptor + A handle used by a process to access files or other input/output resources. + + Procmgr + Process Manager - a QNX system component that manages process creation and execution. + + ASLR + Address Space Layout Randomization - a security technique that randomizes the memory layout of processes. + + Liveliness + Term indicating that a :term:`Component` is periodically sending an + alive notification (using the + :need:`logic_arc_int_op__lifecycle__report_health` interface) as + per configuration. + + QNX + A real-time operating system commonly used in embedded systems. + + DSS + Device Safe State - a safe operational state that a system can enter during failures. + + DAG + Directed Acyclic Graph - a data structure used to represent dependencies between processes. + + Fallback Run Target + A designated Run Target that the system can switch to in case the current active Run Target resp. one of its components fails. From 6c743399dacaa1b247289fb7d13f1d82763aced9 Mon Sep 17 00:00:00 2001 From: Maciej Kaszynski Date: Fri, 9 Oct 2026 09:25:36 +0100 Subject: [PATCH 2/2] Using newer score release --- BUILD | 4 ++++ docs/features/lifecycle/glossary_detailed.rst | 6 ------ docs/features/lifecycle/index.rst | 1 + 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/BUILD b/BUILD index b539fee41c..32a67ee2f5 100644 --- a/BUILD +++ b/BUILD @@ -131,6 +131,10 @@ docs_bundle( docs( bundles = [ + { + "bundle": "//score/launch_manager:docs", + "mount_at": "components/launch_manager", + }, { "bundle": "//score/health_monitor:docs", "mount_at": "components/health_monitor", diff --git a/docs/features/lifecycle/glossary_detailed.rst b/docs/features/lifecycle/glossary_detailed.rst index 131142fb12..9f9d9e0dfa 100644 --- a/docs/features/lifecycle/glossary_detailed.rst +++ b/docs/features/lifecycle/glossary_detailed.rst @@ -41,12 +41,6 @@ Glossary ASLR Address Space Layout Randomization - a security technique that randomizes the memory layout of processes. - Liveliness - Term indicating that a :term:`Component` is periodically sending an - alive notification (using the - :need:`logic_arc_int_op__lifecycle__report_health` interface) as - per configuration. - QNX A real-time operating system commonly used in embedded systems. diff --git a/docs/features/lifecycle/index.rst b/docs/features/lifecycle/index.rst index 8e19e5b37b..d4ffb1d391 100644 --- a/docs/features/lifecycle/index.rst +++ b/docs/features/lifecycle/index.rst @@ -33,3 +33,4 @@ For the main feature description and requirements, see the belonging Feature in safety_planning/index security_planning/index glossary + glossary_detailed