HOWTO Write Specifications for Packages which are to be Distributed using mingw-get

Page under construction: this page will be developed as the mingw-get package specification evolves, and as time permits.


Introduction

mingw‑get, (a.k.a. the MinGW Installer or the MinGW Installation Manager), is a tool to facilitate the download of MinGW software packages from the MinGW.org Project's software repository, on SourceForge, and the installation of these packages on the end user's computer. Controlled by a collection of package lists and package specifications, each of which is distributed in the form of an XML document, and cognizant of inter-package dependencies, it provides a convenient method for users to install a MinGW system, configured to meet each individual user's requirements, and subsequently, to keep the installation up-to-date, as new releases of the installed packages become available.

This document describes the structure of the XML documents, which constitute the package lists and package specifications, and offers guidance to package maintainers, to assist them in the creation and distribution of these specification documents, and the packages to which they refer.

The Anatomy of a Package Specification

From a technical perspective, mingw‑get uses a non-validating XML parser, built on the TinyXML code base, to read package list and package specification documents. In principle, this means that mingw‑get should be capable of loading any well formed XML document, irrespective of its content. In practice, this capability is of limited value: it does allow the parser to accommodate an evolving specification language, by simply — and silently — ignoring any element which it is not yet equipped to handle, (although a validating parser should be able to handle this, through association with an evolving document type definition or XML schema); more usefully, perhaps, it avoids the overhead of repeated validation of specification documents which remain, mostly, static throughout their lifetimes. Conversely, it does mean that mingw‑get could expend overhead, while loading specification documents which are effectively meaningless to it.

Although mingw-get can informally parse any well formed XML document, to avoid potentially wasted XML parsing overhead, a formal definition of the specification language, as it is currently understood by mingw-get, is provided within this XML Schema Definition; (this is incorporated as a component of mingw‑dist — the source code management framework hosted within MinGW.org's git repository, and used by MinGW.org's own package maintainers, to manage their own package specifications — where it is accompanied by this free-standing XML validation tool). By using this XML Schema Definition, together with the accompanying validation tool, package maintainers are able to verify, prior to distribution, that their package specifications comprise only valid content, which may be meaningfully interpreted by mingw‑get.

Readers who are conversant with XSDL — XML Schema Definition Language — may observe that this one XML schema definition is applicable to both package lists, and to package specifications, with both sharing a common root element type: the software‑distribution element. Thus, regardless of whether we are defining a package list, or a package specification — or indeed, a hybrid package list/specification, which is perfectly legitimate, and may be appropriate for a small project distributing relatively few packages — we always begin by defining the software‑distribution document root element, as specified below; within this, we then define, strictly in the following order, at most one optional package‑group‑hierarchy specification, followed by an arbitrary number (i.e. zero or more) package‑list reference specifications, and finally, by an arbitrary number (again, zero or more) package‑collection specifications.

Defining the Document Root Element for a Package Specification

As noted in the general description of the anatomy of a package specification document, the document root element is always a software‑distribution element; the definition of this should be preceded by an appropriate XML document type declaration:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
Thus, you may then define the software‑distribution document root element, which takes the form:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<software-distribution project="FooProject" home="http://foo.project.org" issue="2014051100">

  <package-group-hierarchy>
    ...
  </package-group-hierarchy>

  <package-list ... />
  :

  <package-collection subsystem="collection_name">
    ...
  </package-collection>
  :

</software-distribution>

The following attributes may be specified for the software‑distribution element:

project (string, optional)

You may use this attribute to identify the project which provides the software distribution, to which this package specification relates. The intent is documentary, and its use is recommended; however, the information provided is not used by mingw‑get.

home (URL, optional)

You may use this attribute to identify the URL for the home page of the associated project's web site, (if appropriate). Once again, the intent is documentary; mingw‑get does not refer to this URL.

issue (serial‑number, required)

You must specify a value for this attribute!

Notionally, the XML schema defines the associated serial‑number data type as a ten character string, with its content restricted to any combination of the ten decimal digits, 0..9, and the twenty six upper case roman letters, A..Z; alternatively, it may be specified as the explicit template, "@YYYYMMDDNN@". mingw‑get uses the assigned value to determine when a local copy of your package specification document should be updated, to match a more recent online master copy.

If you are maintaining package specifications for mingw‑dist, or if you are using a framework derived from mingw‑dist to manage your own package specifications, you should use the template form of assignment for this attribute; otherwise, you are advised to assign a ten digit numeric value, based on publication date in the form "YYYYMMDDNN", (where "NN" represents a two digit serialization suffix) — it is important to ensure that the assigned value is increased (lexically), for each successive publication; use of a date based serialization is a convenient mechanism for ensuring this.

The content of the software‑distribution element should comprise child elements, as illustrated in the example above, and as further prescribed below. Any one such child element alone is sufficient to produce a valid package specification document; at least one must be included.

You should not define any text content directly within the software‑distribution element. If you do so, mingw‑get will simply ignore it; however, the mingw‑dist XML schema definition forbids it, and if you use the validation tool, it will reject your document.

Site Status

Site maintenance completed May 25th, 2012 at 12:38 UTC