Skip to content

Package catalogs and the workbench

nxpackage is an fpGUI workbench for editing package metadata, catalogs and Nexus Build projects. It validates the current unsaved source without building products or acquiring dependencies. The metadata dialect and Nexus Build project dialect are distinct; choose the one appropriate to the document being edited.

nxbuild project documents

The workbench opens .nxproject files and ProjectIndex catalogs using nxbuild's universal project dialect. Project validation consumes the current unsaved Nexus Script source through the shared nxbuild loader and graph/planner. It checks requirements and inherited paths without executing producers or requiring a native compiler. Project target selection defaults to the native host; the model's SetTarget operation selects another context and invalidates old results.

Metadata documents

The metadata dialect's four shared roots are Package, Project, PackageIndex, and RepositoryIndex. The common dialect declares metadata; Nexus Forge composes the same contract properties with ordered build children. The editor can inspect a Nexus Forge descriptor without preparing or executing its build. The shared read-only validator lives in src/obNXPackageContractValidator.pas; there is no dependency from this project to the Nexus Forge executor.

Build with nxbuild /action=build /project=projects/nxpackage/nxpackage.nxproject using its configured native Windows toolchain. Open the application and choose a file from ../nexus-lab/examples/packages/catalogs/, or pass an example filename on the command line. The editable pane embeds the reusable TNXScriptEditor widget. F2 or double-click edits a value or definition name; right-click or Insert offers the actions allowed by the document's dialect. Ctrl+Z and Ctrl+Y undo and redo accepted edits. Save and Reload operate on the widget's document, and unsaved changes are confirmed before opening another file, reloading, or closing.

The read-only script pane and diagnostics update after accepted edits. The script pane displays the current source, including comments and dialect declarations, rather than the compiled definitions. Validate reruns the checks against the current unsaved source. The widget owns the editing state, undo history, dirty tracking, and byte-preserving save; nxpackage validates a read-only source snapshot for package/index boundary checks. Rejected edits appear in the diagnostics pane without changing the accepted source.

Package declarations

Package requires a nonblank Id. Version, Author, Description, and License are optional text metadata. Package is authoritative for its intrinsic metadata and requirements. Requires is an optional array of ordinary Nexus Script references to LocalPackage or ExternalPackage records in one explicitly imported PackageIndex or RepositoryIndex. An absent or empty array means no requirements and needs no index.

module NexusPackages "RepositoryIndex.nxscript";

Package Example {
    Id: "NXRP.Example";
    Requires: [@NexusPackages.NexusLib, @NexusPackages.SQLite];
}

The module is an available local Nexus Script document, not a remote repository lookup. Missing modules/records produce diagnostics. Binding a record does not obtain or satisfy the represented package. Unavailable package content and unreachable canonical repository addresses remain valid declarations. Quoted IDs, Id-property references, repository targets, and inline dependency definitions are rejected. Optional array labels are language labels, not IDs. Multiple imported indexes are diagnosed as ambiguous when requirements need a context; no catalog is selected or merged implicitly. Compiler lookup between unrelated local roots is unchanged.

The human identity convention is <ReleaseEntity>.<PackageName>[.<optional qualifiers>...], for example NXRP.NexusScript, FreePascal.FPC, or an independently released NXRP.FPC. The complete ID is opaque: its spelling and case are preserved, its parts are not parsed, and identity is not derived from a filename, definition label, repository, version, or license. Naming and global uniqueness remain authoring responsibilities; the workbench does not certify them.

Package additionally exports optional text arrays Outputs, UnitPaths, IncludePaths, and LibraryPaths. Values may describe files that do not exist yet. Inspection never requires building them. Named Outputs entries can be referenced with ordinary Nexus Script syntax, for example @Library.Outputs.Binary.

Project shares Id, descriptive metadata, Requires, and Outputs, but rejects UnitPaths, IncludePaths, and LibraryPaths: its public contract describes produced artifacts. Compilation paths still belong on an explicit compiler operation in a Nexus Forge Project. The common dialect itself permits no executable children; the Nexus Forge extension supplies those. Neither contract implies dependency acquisition, automatic builds, or output freshness checks.

Machine and published-repository catalogs

PackageIndex is the machine-level catalog: packages with local descriptor locations, known repositories, and packages reachable through those repositories. The package pool's local index can span several repository checkouts.

RepositoryIndex is one repository's published catalog. Its LocalPackage records describe packages supplied by that repository. Trusted sister repositories and ExternalPackage records describe external sources and requirements; they do not claim those packages are supplied here.

Both indexes contain zero or more direct children of these kinds:

Record Required fields Purpose
LocalPackage Id, Descriptor A local descriptor in PackageIndex; a package supplied here in RepositoryIndex.
TrustedRepository Source An explicitly trusted canonical source-control repository.
ExternalPackage Id, Repository A package available through that trusted repository, not supplied locally.

Record labels are Nexus Script reference names, not identities. ExternalPackage's Repository is a single @ reference to a TrustedRepository declared by the same index. A repository in another index cannot satisfy this association or expand trust. Source is preserved canonical repository-address text, not a mirror, descriptor URL, or download command. There is no mirror, fallback, equivalent-source, automatic traversal, reciprocal trust, or transitive trust behavior.

RepositoryIndex NexusPackages {
    TrustedRepository ExternalPackages {
        Source: "<canonical source-control address of nexus-packages-ext>";
    }
    LocalPackage NexusLib {
        Id: "NXRP.NexusLib";
        Descriptor: "NexusLib/Package.nxscript";
    }
    ExternalPackage SQLite {
        Id: "SQLite.SQLite";
        Repository: @NexusPackages.ExternalPackages;
    }
}

Declared records are the catalog, not directories to scan. Descriptor is a relative file locator based on the index document's directory. For RepositoryIndex it locates a descriptor in that repository; for PackageIndex it locates a descriptor in the machine's package pool. URLs, absolute paths, search masks, and explicit directory-only locators are rejected. File existence, descriptor identity agreement, and repository-root containment at retrieval time are not checked; no descriptor is opened while validating the index. LocalPackage has no repository selector. ExternalPackage records an Id and repository association, not a duplicated remote address or descriptor path.

Both package-record kinds allow optional Version and Description for catalog browsing without opening descriptors. These are advertised summaries, not overrides of the authoritative Package. Author, License, Requires, and arbitrary metadata are not duplicated. No automatic synchronization, summary reconciliation, duplicate-ID policy, or version-selection/solving policy is performed.

nexus-packages houses our own packages. nexus-packages-ext houses externally authored packages for packaging purposes. A LocalPackage means supplied here, not authored by us: the external RepositoryIndex also uses LocalPackage records for its hosted packages. The first-party repository index explicitly declares trust and the external packages it requires; trust does not automatically import another catalog. Shared hosting does not grant trust. Hosting an external package does not rewrite its package identity, author, or license. The GUI examples illustrate those roles, not the repositories' actual inventories. Repository-address placeholders are labeled and are never contacted.

Provisional content hashes

A LocalPackage may have one provisional ContentHash child, with required nonblank text Algorithm and Digest. These are advertised hash data only: algorithms and digest encodings are not restricted, and nothing is hashed or verified. Hash presence does not establish trust, affect identity, or add dependency data. Do not rely on this field to validate downloaded or installed package contents.

Editing examples

Package.nxscript imports RepositoryIndex.nxscript for illustrative package requirements. PackageIndex.nxscript is the separate machine-catalog example. ExternalPackage.nxscript and ExternalRepositoryIndex.nxscript illustrate an externally authored package whose identity is independent of our hosting. Project contracts use the same metadata rules described above. Dependency resolution and package acquisition remain separate work.

Imported indexes are validated using the compiled sources already loaded by the session. Original reference targets retain declaration identity and repository provenance; projections do not become owned Package children. The Package editor shows only its entry source and offers dialect-filtered reference choices. Open an index separately to edit it, save it explicitly, and reload/revalidate the Package to read that saved context. The GUI does not create module directives or perform hidden multi-document saves.

Project validation starts with the native OS/CPU and BuildConfiguration=Debug. Use the existing target selection to choose another configuration. $BuildConfiguration resolves through the same Nexus Script mechanism used by nxbuild.