________________________________________________________________________

This file is part of Logtalk <https://logtalk.org/>  
SPDX-FileCopyrightText: 1998-2026 Paulo Moura <pmoura@logtalk.org>  
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
________________________________________________________________________


`application`
=============

This library provides the `application_common` category and the
`application_protocol` protocol for declaring application metadata,
including optional git-related facts such as repository URL, branch,
commit, author, and commit message, plus optional package and archive
identifiers. Application metadata is typically
consumed by tools such as `sbom`.

The library distinguishes two kinds of information:

- release metadata, such as name, version, description, license,
	distribution location, package identifier, release date, and validity date
- optional source provenance metadata, such as repository URL, branch,
	commit, commit date, author, commit message, and archive identifiers

Source provenance predicates are explicit facts declared by the application.
They are not a reflection of the current status of a local git checkout and
should not be assumed to identify a released artifact unless the application
author chooses to state them for that purpose.


API documentation
-----------------

Open the [../../apis/library_index.html#application](../../apis/library_index.html#application)
link in a web browser.


Loading
-------

To load all entities in this library, load the `loader.lgt` file:

	| ?- logtalk_load(application(loader)).


Testing
-------

To test this library predicates, load the `tester.lgt` file:

	| ?- logtalk_load(application(tester)).


Usage
-----

Define an application metadata object importing the `application_common`
category and declaring the metadata that is known explicitly. For example:

	:- object(my_application,
		imports(application_common)).

		name(my_application).
		version('1.2.3').
		description('Example application metadata object').
		license('Apache-2.0').
		homepage('https://example.com/my_application').
		distribution('https://example.com/my_application/releases/download/v1.2.3/my_application.tgz').
		package('pkg:generic/my_application@1.2.3').
		creators(['Tool: Build pipeline', 'Person: Alice']).
		supplier('Organization: Example Application').
		originator('Organization: Upstream Project').
		repository('https://example.com/my_application.git').
		repository_branch(main).
		repository_commit('0123456789abcdef0123456789abcdef01234567').
		git_object_identifier('gitoid:commit:sha1:0123456789abcdef0123456789abcdef01234567').
		software_heritage_identifier('swh:1:rev:0123456789abcdef0123456789abcdef01234567').
		repository_commit_author('Alice').

	:- end_object.

The library distinguishes between creators and originator using two
predicates:

- `creators/1` identifies the people, organizations, or tools credited with
	creating the application or preparing its release metadata
- `originator/1` identifies the original source of the software when that is
	relevant and distinct from the creators

For example, an internal application might use the same party for both
`creators/1` and `originator/1`. A packaged or redistributed application may
use `creators/1` for the team or toolchain preparing the release metadata and
`originator/1` for the original upstream source.

The imported category provides a default definition for the `loader_file/1`
predicate and derived external references that use the same vocabulary as the
corresponding first-class predicates:

- `external_reference(homepage, URL)` from `homepage/1`
- `external_reference(distribution, URL)` from `distribution/1`
- `external_reference(package, Identifier)` from `package/1`
- `external_reference(repository, URL)` from `repository/1`
- `external_reference(git_object_identifier, Identifier)` from `git_object_identifier/1`
- `external_reference(software_heritage_identifier, Identifier)` from `software_heritage_identifier/1`

The following predicates are intended to help tools such as `sbom`
export stronger standardized references:

- `package/1`
	Stores an application package identifier as a PURL. This is distinct from
	`distribution/1`, which stores a download location URL. Tools such as
	`sbom` can use `package/1` to export a package identity reference instead of
	only a release download location. Example:
	`package('pkg:generic/my_application@1.2.3')`.
- `git_object_identifier/1`
	Stores a standardized Git object identifier as a gitoid. This is
	distinct from `repository_commit/1`, which stores the raw commit hash as
	provenance metadata. Tools such as `sbom` can use `git_object_identifier/1`
	to export a stronger provenance reference. Example:
	`git_object_identifier('gitoid:commit:sha1:0123456789abcdef0123456789abcdef01234567')`.
- `software_heritage_identifier/1`
	Stores a Software Heritage identifier (SWHID) for an archived release or
	revision. Tools such as `sbom` can use it to export a stable archived source
	provenance reference when one is known. Example:
	`software_heritage_identifier('swh:1:rev:0123456789abcdef0123456789abcdef01234567')`.

Git-related predicates are optional source provenance facts, not reflection
over the current state of a local repository checkout.

Release-oriented metadata typically includes:

- `name/1`
- `version/1`
- `description/1`
- `license/1`
- `homepage/1`
- `distribution/1`
- `package/1`
- `creators/1`
- `supplier/1`
- `originator/1`
- `built_date/1`
- `release_date/1`
- `valid_until_date/1`
- `external_reference/2`

Optional source provenance metadata typically includes:

- `repository/1`
- `repository_branch/1`
- `repository_commit/1`
- `repository_commit_abbreviated/1`
- `repository_commit_date/1`
- `repository_commit_author/1`
- `repository_commit_message/1`
- `git_object_identifier/1`
- `software_heritage_identifier/1`
