doc: add lots of sample files

doc/package-manifest.json

@@ -0,0 +1,31 @@
+{
+	"Name": "sample-package",
+	"Architecture": "amd64",
+	"Version": "1.2.5-2",
+	"Priority": "optional",
+	"Category": "misc",
+	"Maintainer": "John Doe <john@sample.com>",
+	"Provides": [
+		{ "Name": "sample-api", "Version": "1.2.5" }
+	],
+	"Depends": [
+		{ "Name": "libc", "Version": "2.0", "Predicate": ">=" },
+		{ "Name": "libstdc++", "Version": "2.3", "Predicate": ">=" },
+		{ "Name": "libc", "Version": "2.0", "Predicate": ">=" },
+		{
+			"One-Of": [
+				{ "Name": "libs1", "Version": "1.0", "Predicate": ">=" },
+				{ "Name": "libs2", "Version": "1.2", "Predicate": ">=" }
+			]
+		}
+	],
+	"Recommends": [ "sample-cli" ],
+	"Suggests": [
+		{ "One-Of": [ "sample-gtk", "sample-qt" ] },
+		{ "Name": "libc", "Version": "2.0", "Predicate": ">=" }
+	],
+	"Conflicts": [ "example-package" ],
+	"Enhances": [ "basic-package" ],
+	"Description": "A sample package",
+	"Installed-Size": 3245
+}

doc/package-readme.txt

@@ -0,0 +1,25 @@
++------------------------------------------------------------------------------+
+|                             A Sample Package                                 |
++------------------------------------------------------------------------------+
+
+   This is a sample package to demonstrate the layout and features of a Rosetta
+   package.
+
+
+1 Main Package Layout
+=====================
+
+
+2 The Payload Package
+=====================
+
+
+3 The Control Package
+=====================
+
+
+4 The Meta Package
+==================
+
+
+vim: shiftwidth=3 expandtab

doc/package-versions.txt

@@ -0,0 +1,124 @@
++------------------------------------------------------------------------------+
+|                   Rosetta Package Manager Documentation                      |
+|                   .....................................                      |
+|                   Package Version Format and Comparison                      |
++------------------------------------------------------------------------------+
+
+   This document describes the format of Rosetta package version indicators, and
+   the way in which they are compared.
+
+
+1 Permitted Characters
+======================
+
+   The following characters can be used in a package version identifier:
+   -  lowercase letters [a-z]
+   -  digits [0-9]
+   -  the following punctuation: - . ~
+
+
+2 Version String Format
+=======================
+
+   The package version identifier should have the following layout:
+
+   [release-phase]<upstream-version>[~version-version-phase[version-release-phase-revision]][-package-revision]
+
+   Components surrounded by [square brackets] is optional, while components
+   surrounded by <triangular brackets> are required. If a component name
+   is preceded by a punctuation mark, the value of that component in a package
+   version identifier must also be preceded by that punctuation mark.
+
+   The different version identifier components are defined as follows:
+   -  release-phase (optional) indicates the release stage of the upstream
+      software. allowable values are: alpha, beta
+
+   -  upstream-version (required) indicates the version number of the upstream
+      release. this is made up of one to five integers >= 0 separated by full
+      stops.
+
+   -  version-release-phase (optional) indicates the release stage of this
+      particular version of the upstream software. allowable values are:
+      alpha, beta, rc.
+
+   -  version-release-phase-revision (optional) indicates the revision of the
+      upstream package version within a given pre-release-version. must be
+      a positive non-zero integer.
+
+   -  package-revision (optional) indicates different versions of a particular
+      package that contain the same version of the upstream software.
+
+   Some examples of package versions include:
+   -  1.0.0
+      First revision of package for upstream release 1.0.0
+
+   -  beta1.7
+      First revision of package for upstream beta pre-release 1.7
+
+   -  0.6-2
+      Second revision of package for upstream release 0.6
+
+   -  1.2~beta2
+      First revision of package for the second beta pre-release of upstream
+      version 1.2
+
+   -  5.15~rc1-2
+      Second revision of package for the first release-candidate pre-release of
+      upstream version 5.15
+
+
+3 Version Comparison
+====================
+
+   There are a number of rules that govern how package version identifiers are
+   compared.
+
+
+   3.1 Comparison Procedure
+   ------------------------
+
+   When comparing two version numbers, the five components are compared left to
+   right using the following procedure:
+   1. release-phase is compared according to Release Phase Precedence. If the
+      two packages have different release-phase values, the one with higher
+      precedence is considered the newer package. If one package does not have
+      a release-phase, a release-phase of 'release' is assumed, which has the
+      highest precedence.
+
+   2. Each digit in upstream-version is compared left-to-right. If one package
+      version has fewer digits than the other, the missing digits are assumed to
+      be zero. If one package has a version digit greater than the other when
+      read left-to-right, it is considered the newer package.
+
+   3. version-release-phase is compared according to Release Phase Precedence.
+      If the two packages have different version-release-phase values, the
+      one with higher precedence is considered the newer package. If a package
+      does not have a version-release-phase, a value of 'release' (with the
+      highest precedence) is assumed, and step 4 is skipped.
+
+   4. The package with the greater version-release-phase-revision is considered
+      the newer package. If a package does not have a
+      version-release-phase-revision, a value of one is assumed.
+
+   5. The package with the greater package-revision is considered the newer
+      package. If a package does not have a package-revision, a value of one is
+      assumed.
+
+   If each of the five components of two package versions is determined to be
+   equal according to the above procedure, the two packages are considered to
+   be equal in version.
+
+
+   3.2 Release Phase Precedence
+   --------------------------
+
+   Release phases have a defined order of precedence which is used during
+   comparisons. This order, in decending level of precedence, is:
+   1. release (cannot be specified directly, but is used implicitly if no
+      release phase is specified).
+   2. rc
+   3. beta
+   4. alpha
+
+
+vim: shiftwidth=3 expandtab

doc/release.json

@@ -0,0 +1,9 @@
+{
+	"mango-kernel": {
+		"0.1": {
+		}
+	},
+	"rosetta-system": {
+		"0.1": {
+	}
+}

doc/sample-package/control/post-install.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "Hello, world!"

doc/sample-package/control/post-uninstall.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "Hello, world!"

doc/sample-package/control/pre-install.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "Hello, world!"

doc/sample-package/control/pre-uninstall.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "Hello, world!"

doc/sample-package/make-package.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+payload_name=payload.tar.zst
+control_name=control.tar.zst
+news_name=news.tar.zst
+manifest_name=manifest.json.zst
+
+payload_dest=$TMPDIR/$payload_name
+control_dest=$TMPDIR/$control_name
+news_dest=$TMPDIR/$news_name
+manifest_dest=$TMPDIR/$manifest_name
+
+pkg_dest=sample-package_0.1_amd64.ropkg
+
+rm -rf $manifest_dest
+
+tar cf $payload_dest --zstd -C payload .
+tar cf $control_dest --zstd -C control .
+tar cf $news_dest --zstd -C news .
+zstd manifest.json -o $manifest_dest
+
+tar cf $pkg_dest -C $TMPDIR $payload_name $control_name $news_name $manifest_name

doc/sample-package/manifest

@@ -0,0 +1,17 @@
+Name: sample-package
+Architecture: amd64
+Version: 1.2.5-2
+Priority: optional
+Category: misc
+Maintainer: John Doe <john@sample.com>
+Provides: sample-api (= 1.2.5)
+Depends: libc (>= 2.0), libstdc++ (>= 2.3), libs1 (>= 1.0) | libs2 (>= 1.2)
+Recommends: sample-cli
+Suggests: sample-gtk | sample-qt, sample-server
+Conflicts: example-package
+Enhances: basic-package
+Description: A sample package
+Installed-Size: 3245
+
+This is a sample package that demonstrates the structure of a Rosetta package,
+as well as the layout of the associated manifest and news files.

doc/sample-package/news/20250707.01.news

@@ -0,0 +1,110 @@
+PublishDate: 2025-07-07 09:00:00
+Importance: Normal
+Title: Welcome to the Rosetta Package Manager
+Category: General
+
++------------------------------------------------------------------------------+
+|                   Welcome to the Rosetta Package Manager!                    |
++------------------------------------------------------------------------------+
+
+   This is a sample news item to introduce you to the Rosetta package manager.
+   These news items can be used to provide information and updates to those who
+   use your repository.
+
+
+1 News File Location
+====================
+
+   News items come from four different sources:
+   -  Repository-wide news items, located in /news
+
+   -  Channel-related news items, located in /channel/<channel-id>/news
+
+   -  Component-related news items, located in
+      /channel/<channel-id>/component/<component-id>/news
+
+   -  Package-related news items, included in individual package files.
+
+   Specific news items can be published in different locations depending on who
+   the news is relevant for. For example, if there is some critical issue that
+   affects all users of a repository, /news would be the perfect place to use.
+   If, instead, the issue only affects users of a particular channel (maybe
+   you have a channel for each release of your operating system),
+   /channel/<channel-id>/news would be more appropriate. It's important that
+   news is targeted to the appropriate audience so that users don't have to sift
+   through news that isn't relevant to them.
+
+
+2 News File Format
+==================
+
+   News items have a specific plain-text format, which can be seen in this file.
+   The file begins with a set of headers that describe certain attributes of the
+   news, followed by the news content and an optional footer.
+
+
+   2.1 Header And Footer
+   ---------------------
+
+   These headers include:
+   -  PublishDate: The date and time on which the news item was published. This
+      is used by clients to determine which news items have been released since
+      the user last checked the news. This is always in UTC.
+
+   -  Title: The title of the news item.
+
+   -  Category: The particular category that the news item is relevant to.
+      Possible values include:
+      *  General
+      *  Security
+
+   -  Importance: How important it is that the user reads this news.
+      Possible values include:
+      *  Low
+      *  Normal
+      *  High
+      *  Critical
+      The user has to go out of their way to read Low and Normal news items, while
+      High and Critical news items will be shown automatically when the user next
+      interacts with the relevant part of the repo.
+
+   Immediately following these headers are two line-feed characters. This
+   denotes the end of the header and the start of the content of the news files.
+   With two line feeds, there should be exactly one blank line visible between
+   the last header line and the first content line.
+
+   At the end of the file is a line with 5 asterisk (*) characters. This denotes
+   the end of the of the news file's content and the start of the footer. Beyond
+   this point, you can put extra data, such as the vim formatting commands
+   visible in this file, that you don't want shown to the user. If no footer is
+   required, the 5-asterisk marker can be omitted, and the news content will
+   simply end where the file ends.
+
+
+   2.2 Content
+   -----------
+
+   Between the header and footer is the actual news content that is shown to the
+   user. This section can be formatted in any way you prefer; any plaintext is
+   acceptable. This news file has been formated in a particular way to provide
+   example formatting that you may wish to use. It features a page header,
+   section and sub-section headings, and list formatting. All paragraphs
+   are indented with three spaces. The gap between a list item marker
+   and list item text is two spaces, with any following lines in that particular
+   list item indented with three spaces. There is one blank line between each
+   paragraph, and two blank lines between the last line in one section and
+   the heading of the next.
+
+   The only formatting rule that should be adhered to is that, like code, lines
+   should be kept to no longer than 80 characters. This is due to the fact that
+   the vast majority of users will be viewing news items within their terminal
+   as they are using the ropkg commands, and 80 cells is the standard width for
+   terminal displays.
+
+   Don't forget that, if your text editor supports in-line formatting directives
+   like vim, you can store these directives in the page footer so that they
+   aren't shown to the user.
+
+*****
+
+vim: shiftwidth=3 expandtab

doc/sample.recipe

@@ -0,0 +1,46 @@
+import ropkg
+
+
+package_manifest = {
+    'Name': 'rosequartz',
+    'Version': '1.0',
+    'Maintainers': [ 'Max Wash <max@doorstuck.net>' ],
+    'Arch': ropkg.system.arch(),
+    'Platform': ropkg.system.platform_name(),
+    'Description': 'Cross platform C and C++ runtime',
+    'Depends': [ 'libc:1.0', 'libm:1.0'],
+    'License': '3-Clause BSD',
+    'Website': 'http://doorstuck.net',
+    'SourceWebsite': 'https://gitlab.com/doorstuck/rosequartz'
+}
+
+
+def get_sources():
+    ropkg.git.clone_repo('rosequartz', 'https://gitlab.com/doorstuck/rosequartz.git')
+
+
+def configure():
+    ropkg.cmake.configure_project('rosequartz')
+
+
+def build():
+    ropkg.build.build_project('rosequartz')
+
+
+def package():
+    ropkg.pkg.build_package('rosequartz', package_manifest)
+
+
+recipe = {
+    'name': 'rosequartz',
+    'steps': {
+        'get-src': get_sources,
+        'configure': configure,
+        'build': build,
+        'package': package,
+    }
+}
+
+ropkg.run_recipe(recipe)
+
+# vim: ft=python