Volume 19: Package and Dependency Management¶

1. Introduction¶

This volume defines the Rethon package and dependency management model, including RETPAK. It describes the package model, RETPAK, project manifests, retpak.toml, package names, package versions, dependencies, development dependencies, package archives, .rpk files, source file extension, .re files, package imports, standard library boundary, external package boundary, native packages and FFI, package locking, publishing packages, package registry, security and trust, future extensions, and summary.

This document is part of the official Rethon Language Specification. It is normative rather than descriptive. Implementations, tooling, documentation systems, and other source-processing tools shall treat the rules in this volume as authoritative.

This volume does not define registry transport details, network protocol details, build-system internals, or backend implementation details. It defines the source-level and language-level direction for package and dependency management.

Rethon is Python-inspired in language philosophy and Python-first in surface syntax where practical. It uses modules as source-level namespaces, Python-like imports, public-by-default visibility, compiler-enforced private visibility, a general-purpose standard library, external and domain-specific functionality through packages, RETPAK as the Rethon package manager, .re as the source file extension, .rpk as the package archive extension, and retpak.toml as the project manifest.

Packages shall provide external and domain-specific functionality that is outside the core standard library.

2. Package Model¶

A package shall be a distributable unit of Rethon code and related assets.

A package shall group modules, metadata, dependencies, and any other source-level assets that are part of the package contract.

A package shall not be confused with a module.

See Volume 10 for the normative distinction between modules as source-level namespace units and packages as distribution and dependency-management units.

A module shall remain a source-level namespace.

A package shall contain one or more modules, and those modules shall remain the source-level units of namespace and visibility.

Example:

module text.formatting:
    public def slugify(value: str) -> str:
        ...

Packages shall be the unit of distribution and dependency management.

Modules shall be the unit of source-level namespace and name resolution.

A package may provide general-purpose utilities, domain-specific libraries, native bindings, or other installable functionality not included in the standard library.

3. RETPAK¶

RETPAK shall be the official Rethon package manager.

RETPAK shall be the source-level and workflow-level tool used to create, add, remove, update, build, test, and publish packages in the Rethon ecosystem.

Example commands:

retpak init
retpak add package_name
retpak remove package_name
retpak update
retpak build
retpak test
retpak publish

RETPAK shall support ordinary package and dependency workflows without requiring ordinary source code to know registry internals or transport specifics.

RETPAK shall remain compatible with the language's Python-first surface direction and conservative package philosophy.

4. Project Manifests¶

A Rethon project shall be described by a project manifest.

The project manifest shall be named retpak.toml.

The manifest shall describe package identity, dependencies, build-relevant package metadata, and other source-level package information needed by RETPAK.

Example:

[package]
name = "text-utils"
version = "0.1.0"

The manifest shall be the source-level declaration of package intent for ordinary project workflows.

The manifest shall not require build-system internals to be embedded in source code.

5. `retpak.toml`¶

retpak.toml shall be the canonical project manifest file name.

A retpak.toml file shall identify the package, its version, and its dependency declarations in a structured source-readable format.

A retpak.toml file shall remain conservative and readable.

The specification does not require a particular manifest schema beyond the fields and concepts needed by RETPAK and the package model.

Example:

[package]
name = "math-extra"
version = "1.2.0"

The manifest shall be the normal place to describe package metadata consumed by RETPAK.

6. Package Names¶

A package shall have a name.

Package names shall be stable identifiers used for dependency resolution, publication, and human-readable package references.

Package names should normally use lowercase names and may use separators where the manifest or registry conventions permit them.

Package names shall be distinct from module names, type names, function names, and file names, though they may be related by convention.

Example:

text-utils
native-image
crypto-core

Package names shall be conservative and should clearly express the package's purpose.

7. Package Versions¶

A package shall have a version.

Package versions shall support explicit compatibility management and reproducible dependency selection.

The versioning model shall remain source-readable and conservative.

The specification does not require a single concrete numeric scheme here, but it does require that versions be explicit and usable for dependency constraints.

Example:

[package]
name = "text-utils"
version = "1.4.0"

Package versions shall be appropriate for stability management, publication, and locking.

8. Dependencies¶

A package shall be able to declare dependencies on other packages.

Dependencies shall be explicit in the manifest.

Dependencies shall be versioned where practical so that package resolution remains predictable.

Example:

[dependencies]
text-utils = "1.4.0"

A dependency shall represent a package needed for normal operation of the package.

Dependencies shall be resolved by RETPAK using package-level metadata rather than by hidden source inference.

9. Development Dependencies¶

A package shall be able to declare development dependencies.

Development dependencies shall be packages needed for testing, building, documentation, or other development-only workflows.

Example:

[dev-dependencies]
assertions = "0.3.0"

Development dependencies shall not be required for ordinary end-user consumption unless a later packaging rule explicitly says otherwise.

Development dependencies shall keep testing and tooling support separate from runtime dependencies where that separation improves clarity.

10. Package Archives¶

A package archive shall be a distributable package artifact.

Package archives shall provide a portable format for installing or transferring packages.

Package archives shall be explicit and source-level in intent, but the specification does not prescribe archive compression internals or transport details.

Package archives shall support distribution of source packages, native packages, or mixed packages where the package contract permits such forms.

11. `.rpk` Files¶

The package archive extension shall be .rpk.

Example:

text-utils-1.4.0.rpk

An .rpk file shall denote a Rethon package archive.

The specification does not define a particular on-disk encoding or compression format for .rpk files.

The extension is part of the package direction and shall be used consistently by RETPAK and related tooling.

12. Source File Extension¶

The Rethon source file extension shall be .re.

The .re extension shall identify source files containing Rethon code.

The extension shall be used consistently by tooling, editors, and package workflows where source files are referenced by extension.

13. `.re` Files¶

A .re file shall contain Rethon source code.

A package may include one or more .re files as module implementations, entry points, or supporting source files.

Example:

src/main.re
src/text/format.re

A .re file shall remain subject to the language's ordinary syntax, module, and visibility rules.

14. Package Imports¶

Package imports shall occur through the module system and the language's Python-like import syntax.

Example:

import text_utils
from math_extra import clamp

A package shall expose its public API through modules and public declarations.

Importing a package module shall follow the module and import rules established elsewhere in the specification.

Package imports shall not require special runtime magic beyond the package and module model defined in this volume and the module volume.

15. Standard Library Boundary¶

The standard library shall remain general-purpose.

Core language-adjacent types and utilities belong in the standard library only when they are broadly useful and conservative enough to serve ordinary application code.

Domain-specific functionality shall be delivered through packages rather than through the core standard library.

The standard library shall not absorb specialized ecosystems simply because they are popular in one domain.

Example of boundary intent:

# graphics, audio, physics, and engine APIs belong in packages, not the core standard library

16. External Package Boundary¶

External and domain-specific functionality shall be provided through packages.

Packages shall be the normal place for game-specific, graphics, audio, physics, and other specialized APIs.

Packages shall also be the normal place for application-specific utility libraries and domain frameworks.

Packages shall preserve the language's source-level typing and visibility rules.

17. Native Packages and FFI¶

Native packages shall be supported.

A package may provide native bindings, FFI wrappers, or other interoperability layers.

Native bindings shall remain explicit and shall obey the foreign-function interface rules established elsewhere in the specification.

Example:

native-math
sqlite-bindings

Native packages shall be distributable through RETPAK.

Native packages shall not weaken the memory-safety-by-default model for ordinary safe code.

18. Package Locking¶

Package locking shall be supported in principle.

A lock mechanism shall support reproducible resolution of package dependencies for a given project.

The specification does not prescribe lock-file internals, conflict algorithms, or resolver implementation details in this volume.

A lock mechanism shall help preserve consistent builds and dependency selection across environments.

19. Publishing Packages¶

Publishing packages shall be supported.

RETPAK shall provide a publish workflow for making packages available to other projects.

Package publishing shall be explicit and should preserve version clarity, dependency metadata, and package identity.

The specification does not define registry transport or publication protocol details in this volume.

20. Package Registry¶

The package registry shall be acknowledged but its details may be deferred.

The specification shall not define registry implementation details, network protocol details, or hosting model details in this volume.

A registry may exist to distribute packages, but the exact registry architecture is not part of the source-level package model.

RETPAK and the package manifest shall remain usable as source-level concepts even while registry details evolve.

21. Security and Trust¶

Package security and trust shall be considered explicit concerns.

Package tooling shall be designed to support verification, integrity, and conservative trust boundaries where practical.

The specification does not prescribe a particular signing or trust protocol in this volume.

Users and tooling shall remain able to reason about where a package came from, what version it is, and how it participates in the dependency graph.

Packages with native components or privileged behavior shall be treated with appropriate caution.

22. Future Extensions¶

This volume defines the current direction for package and dependency management in Rethon, but future specification work may refine the model in carefully controlled ways.

Possible future extensions include:

richer manifest fields
additional dependency categories
more precise version range semantics
lockfile format details
registry trust mechanisms
package signing and verification
workspace or multi-package project support
additional package metadata for native bindings

Any future extension shall preserve the current direction:

RETPAK remains the official package manager
retpak.toml remains the manifest name
.re remains the source file extension
.rpk remains the package archive extension
modules remain source-level namespaces
standard library scope remains general-purpose
specialized domains remain in packages
native bindings remain supported through packages and FFI
registry and transport details remain outside the core source-level package contract

23. Summary¶

RETPAK shall be the official Rethon package manager.

retpak.toml shall be the project manifest.

.re shall be the Rethon source file extension, and .rpk shall be the package archive extension.

Packages shall provide external and domain-specific functionality outside the general-purpose standard library.

Game, graphics, audio, physics, and engine APIs shall live in packages rather than in the core language or standard library.

Native bindings shall be distributable through RETPAK packages and shall obey the FFI rules established elsewhere in the specification.

Package locking and publishing shall be supported in principle.

Registry and transport details may be deferred.

Rethon's package model shall therefore remain Python-first, source-readable, and conservative while supporting a practical ecosystem of external and native packages.

Volume 19: Package and Dependency Management¶

1. Introduction¶

2. Package Model¶

3. RETPAK¶

4. Project Manifests¶

5. retpak.toml¶

6. Package Names¶

7. Package Versions¶

8. Dependencies¶

9. Development Dependencies¶

10. Package Archives¶

11. .rpk Files¶

12. Source File Extension¶

13. .re Files¶

14. Package Imports¶

15. Standard Library Boundary¶

16. External Package Boundary¶

17. Native Packages and FFI¶

18. Package Locking¶

19. Publishing Packages¶

20. Package Registry¶

21. Security and Trust¶

22. Future Extensions¶

23. Summary¶

5. `retpak.toml`¶

11. `.rpk` Files¶

13. `.re` Files¶