gen-lib

Create and maintain a program-local framework library for Astrobe Oberon programs

Name

gen-lib – create and maintain a program-local framework library

Synopsis

gen-lib update <cfg_file> <mod_file> [-f <avar>] [-l <libdir>] [-a] [-p <pat>] [-v]

gen-lib clean <mod_file> [-l <libdir>] [-d] [-v]

Description

gen-lib manages a program-local copy of the Oberon RTK framework library. It reads the Astrobe configuration file to determine the library search path, resolves the program's import dependencies, and copies the required framework modules into a project-local directory.

Background

Astrobe searches for imported modules starting from the current directory, then follows the directories listed in the configuration file's search path (the LibPathName entries). When a program customises a framework module, the customised version must be found before the original. However, Astrobe's "current folder first" rule can cause the wrong version to be picked during compilation of other modules that import the same name.

gen-lib solves this by creating a project-local library directory (default: rtk-lib) that contains copies of the unmodified framework modules the program needs. The search path is arranged so that the project directory and any customisation directories sit above rtk-lib and are found first, while the local copy provides the remaining framework modules:

project directory      program-specific and customised modules
rtk-lib/               local framework library (managed by gen-lib)
framework dirs ...     original framework installation

The local library makes each program self-contained: it includes the exact framework versions used during development, independent of later framework updates.

What gen-lib Does

The update command:

parses the program module's IMPORT list and recursively resolves all imported modules along the search path
identifies which modules come from framework directories (those below rtk-lib in the search path) – modules that already exist in the project directory or its subdirectories above rtk-lib are not copied, since those are the program's own or customised modules
copies the remaining framework modules into the local library directory
deletes .arm (compiled) files to force recompilation
removes any files in the library directory that are no longer needed

With the -a flag, all framework modules are copied regardless of whether the program imports them, still excluding any that already exist in the project directories above rtk-lib. When the same module name appears in more than one framework directory, the first one found is copied and the duplicates are placed in an ignored/ subdirectory for reference.

The clean command removes compilation artifacts (.arm, .lst, and optionally .smb files) from the library directory, forcing a clean recompilation.

Supported platforms: Windows and macOS.

Commands

update: resolve imports and copy framework modules into the local library directory.
clean: remove compilation artifacts from the local library directory.

Arguments

update

cfg_file: Astrobe configuration file (.ini). Can be a relative or absolute path.
mod_file: program main module file (.mod). Can be a relative or absolute path. Must import Main. The parent directory of this file is used as the project directory.

clean

mod_file: program main module file (.mod). Can be a relative or absolute path. Used to locate the project directory.

Options

update

-f avar: value for the Astrobe search path variable (%AstrobeXXX% entries in the configuration file). Must be an absolute path to an existing directory. Required when the configuration file uses %Astrobe...% path entries.
-l libdir: name of the local library directory. Default: rtk-lib. Created automatically if it does not exist.
-a: copy all framework modules, not just those imported by the program. Modules with names starting with _ and Astrobe's Build.mod are always excluded. When the same module name appears in more than one framework directory, the first one found is copied to rtk-lib/ and the duplicates are placed in the ignored/ subdirectory with a suffix to keep names unique.
-p pat: filter: only copy modules whose full path contains pat. Useful for updating modules from a specific framework subdirectory. Use with caution: a pattern that is too strict can filter out modules needed to maintain consistent import relationships. If the linker reports wrong module versions after a filtered update, the pattern was too restrictive.
-v: verbose output. Lists all updated, added, removed, and ignored modules with full paths.

clean

-l libdir: name of the local library directory. Default: rtk-lib.
-d: deep clean. Also remove symbol files (.smb) that have a corresponding .mod file. Orphaned .smb files (no matching .mod) are always removed.
-v: verbose output. Lists all removed files.

Output

The update command prints a summary:

program module: <path>
config file: <path>
Astrobe var: <value>
file pattern: <value>
'all' option: true/false
project lib: <project>/<libdir>
modules updated:   N
modules added:     N
modules removed:   N
files removed:     N
modules ignored:   N

With -v, detailed lists of individual files are printed before the summary.

Examples

Update

Populate or refresh the local library. gen-lib traces the IMPORT lists recursively starting from the program module and copies the framework modules the program needs. Modules that already exist in the project directory or its customisation directories are not copied – only those that would otherwise come from the framework installation. The -f option supplies the root directory that replaces %AstrobeRP2350% in the configuration file's search path entries:

gen-lib update Prog.ini Prog.mod -f C:\Astrobe\RP2350

program module: C:\Projects\MyApp\Prog.mod
config file: C:\Projects\MyApp\Prog.ini
Astrobe var: C:\Astrobe\RP2350
file pattern: none
'all' option: false
project lib: MyApp\rtk-lib
modules updated:  28
modules added:     0
modules removed:  14
files removed:    28
modules ignored:   0

On the first run, rtk-lib/ is created and all 28 modules are added. On subsequent runs after framework changes, modules are overwritten with fresh copies and any modules no longer in the import tree are removed.

Filtered Update

Update only modules from a specific framework subdirectory. The -p filter matches against the full source path of each module:

gen-lib update Prog.ini Prog.mod -f C:\Astrobe\RP2350 -p kernel-v4

This copies only modules whose framework path contains kernel-v4, leaving all other modules in rtk-lib/ untouched. Useful when only a specific library component has changed.

Clean

Remove compilation artifacts from the library directory. This forces Astrobe to recompile all library modules on the next build:

gen-lib clean Prog.mod

files removed: 56

Without -d, only .arm (object files) and .lst (listing) files are removed. With -d, symbol files (.smb) that have a corresponding .mod file are also removed:

gen-lib clean Prog.mod -d

files removed: 84

Diagnostics

"cannot find program module file" – the specified .mod file does not exist
"is not a program main module, must import 'Main'" – the module does not import Main and is therefore not a program entry point
"cannot find config file" – the specified .ini file does not exist
"Astrobe search path variable … is not an existing directory" – the value given with -f is not a valid directory
"is used in search path, but no value given" – the configuration file contains %Astrobe...% entries but -f was not specified
"framework library directory … not found in config file" – the library directory is not listed in the search path; check the -l value and the LibPathName entries in the .ini file

Notes

The update command always overwrites existing files in the library directory. This is intentional: it allows reverting local experiments by simply re-running the update. The local library modules are not meant to be edited – customised modules belong in the project directory or a separate customisation directory above rtk-lib in the search path.

File timestamps are preserved during copying, so Astrobe can detect which modules need recompilation.

The RP2040 second-stage boot file (boot2.bin) is treated as a library file and copied alongside the module files when found in the search path.

Last updated: 7 March 2026