RepositoryFormat - npackd/npackd GitHub Wiki

Introduction

A repository consists of a single XML file that can be placed on a HTTP server. The file contains package and package version descriptions and references the packages using URLs. This makes at possible to create a software compilation repository with packages from different software vendors.

Since version 3.3 of this specification (Npackd version 1.20) it is also possible to place the repository XML named "Rep.xml" in a ZIP file.

Npackd operates on the list of repositories defined for a particular computer. All definitions in these repositories are combined in the order of the appearance. This means that definitions from earlier defined repositories may hide the definitions from the repositories that stay further in the list. Different parts of a repository like packages, package versions or licenses are referenced by their identifiers. A package version may reference a package that none of the repositories defines. In this case a dummy package with the specified identifier will be automatically created. The same happens if a package references a non-existing license definition

Remark:

  • Npackd 1.19 and later can theoretically download 16 EiB big packages (tested with 13 GiB) and supports .zip files bigger than 4 GiB (zip64 file format)
  • Npackd 1.17 can theoretically download 16 EiB big packages (tested with 8 GiB), but cannot extract .zip files bigger than 4 GiB
  • Npackd 1.16 can theoretically download 16 EiB big packages (tested with 8 GiB), but does not show the progress during the download of files bigger than 2 GiB and cannot extract .zip files bigger than 4 GiB
  • Npackd before 1.16 only can download packages smaller than 2 GiB in size.

Details

The root element should be named root and can contain package and version tags:

<root>
    <!-- 
        (since 2) specification version (1.0 if missing). The first number denotes
        incompatible changes (e.g. 2 is incompatible with 1), the second number
        denotes compatible changes. 
        Npackd 1.13 and earlier versions implement the specification in the version 1. 
        Npackd 1.14 implements the version 2 of the specification.
        Npackd 1.15 implements the version 2.1 of the specification.
        Npackd 1.16 implements the version 3 of the specification.
        Npackd 1.18 implements the version 3.1 of the specification.
        Npackd 1.19 implements the version 3.2 of the specification.
        Npackd 1.20 implements the version 3.3 of the specification.
        Npackd 1.22 ... 1.24 implement the version 3.4 of the specification.
        Npackd 1.26 implements the version 3.5 of the specification.
        Npackd 1.27 implements the version 3.6 of the specification.
    -->
    <spec-version>3.5</spec-version>

    <license ...>
        ....
    </license>
    <license ...>
        ....
    </license>
    ...
    <package ...>
        ...
    </package> 
    <package ...> 
        ...
    </package> 
    ...
    <version ...> 
        ...
    </version> 
    <version ...> 
        ...
    </version> 
    ...
</root>

IDs

IDs are used at different places in the repository XML: as full internal package names, internal license names or package tags. Each ID could be prefixed with a reversed domain name of the software vendor. The last part of the ID is the name of the item in lower case separated with dashes. IDs cannot contain start or end with a dot or contain two dots consecutively. The parts of an ID cannot start or end with a dash or contain two dashes consecutively. Valid characters for the package name parts are: '-', '0'...'9', 'A'...'Z', '_', 'a'..'z' and other Unicode letters.

  • The default repositories hosted at http://www.npackd.org should not use prefixes, if possible.
  • Do not use prefixes, if possible. Example: "blender" is right, "com.blender.blender" is wrong.
  • Please consult https://repology.org/projects/ if choosing a name for a new package.
  • A package name should not contain the name of the vendor. Example: com.mycompany.office is right, but com.mycompany.mycompany-office is wrong.
  • A package name should not contain the "www" suffix. Example: com.mycompany.office is right, com.mycompany.www.office is wrong.
  • See PackageCPPLibraries for how C and C++ libraries should be packaged.

Supported image formats

At least PNG should be supported. Npackd also supports the following formats: "bmp", "cur", "gif", "icns", "ico", "jpeg", "jpg", "pbm", "pgm", "png", "ppm", "tga", "tif", "tiff", "wbmp", "webp", "xbm", "xpm".

The license element

<!--
    the *name* attribute is mandatory and contains the ID of the license.     
-->
<license name="gplv3">
    <!-- (since 2.1/Npackd 1.15) optional one-line title of the license -->
    <title>GPLv3</title>

    <!-- 
        (since 2.1/Npackd 1.15) an optional web page URL for the license description 
        
        (since 3.4/Npackd 1.22) the URL must not be absolute and will be 
        resolved relative to the URL of the repository.
    -->
    <url>http://www.gnu.org/licenses/gpl.html</url>
</license>

The package element

The name attribute is mandatory and is an ID.

<package name="buggy-text-editor">
    <!-- (since 1/Npackd 1.7.0) [0..1] optional one-line name of the Application -->
    <title>The Buggy Editor</title>

    <!-- 
        (since 1/Npackd 1.9.0) [0..1] an optional web page URL for package 
        description. The same value can be supplied using
        the <link rel="homepage" href="..."/> tag.
        
        (since 3.4/Npackd 1.22) the URL must not be absolute and will be 
        resolved relative to the URL of the repository.
     -->
    <url>http://www.example.com/BuggyTextEditor.html</url>

    <!-- (since 1/Npackd 1.9.0) [0..1] an optional description (multiline) -->
    <description>the most buggy editor</description>

    <!--
        (since 2) [0..1] optional URL for the package icon.
        The usual size is 32x32 pixels. The same value can be supplied using
        the <link rel="icon" href="..."/> tag.
        
        (since 3.4/Npackd 1.22) the URL must not be absolute and will be 
        resolved relative to the URL of the repository.
    -->
    <icon>http://www.example.com/BuggyTextEditor/icon.png</icon>

    <!-- (since 2) optional license name -->
    <license>gplv3</license>

    <!-- 
        (since 3.1/Npackd 1.18) [0..n] category. The possible sub-categories should 
        be separated by  a slash "/". 
        See also the list of recommended categories below.
        Implementation note: Npackd 1.18 only supports one category element per package
        and only up to 2 category levels.
    -->
    <category>Text/Editor</category>
    
    <!--
        (since 3.5/Npackd 1.26) [0..n] a tag (an ID). See below for the list of
        standard tags.
    -->
    <tag>end-of-life</tag>

    <!--
        (since 3.5/Npackd 1.26) [0..1] number of stars. Each user can assign a 
        star to a package marking it as his favorite.
    -->
    <stars>12</stars>

    <!-- 
        (since 3.3/Npackd 1.20) this tag is optional. The tag "link" creates a 
        link from this package to another resource on the Internet. Npackd only
        supports "http:" and "https:" URL schemes. The valid 
        values for the attribute "rel" are:
        - "homepage"  an optional web page for package description. It is 
            recommended to use the "url" tag instead for backward compatibility. 
            Npackd only supports one home page per package.
        - "icon" package icon. The usual size is
            32x32 pixels. It is recommended to use the "icon"
            tag instead for backward compatibility. Implementation note: Npackd
            only can use one icon in the UI.
        - "changelog" web page for the package change log. Npackd only supports
            one change log per package.
        - "screenshot" screen shot. Multiple screen shots are allowed.
        - (since 3.5/Npackd 1.26) "issues" issue tracker where you can see the list and 
            possibly file bugs and enhancements.
        The attribute "href" is mandatory and should contain a valid URL to the
        resource.
        
        (since 3.4/Npackd 1.22) the URL must not be absolute and will be 
        resolved relative to the URL of the repository.
    -->
    <link rel="homepage" href="http://www.example.com/BuggyTextEditor"/>
    <link rel="icon" href="http://www.example.com/BuggyTextEditor/icon.png"/>
    <link rel="changelog" href="http://www.example.com/BuggyTextEditor/ChangeLog.html"/>
    <link rel="screenshot" href="http://www.example.com/BuggyTextEditor/Screen.png"/>
    <link rel="issues" href="http://www.example.com/issues"/>
</package>

Categories

List of recommended categories:

  • Communications: communications (social media, messaging, call management, etc.)
  • Dev: software development (libraries, IDEs, SDKs, etc.)
  • Education: education (educating, teaching, learning)
  • Finance: finance (managing personal finances, banking, payments, ATM finders, financial news, insurance, taxes, portfolio, trading, tip calculators)
  • Games: games
  • Music: music (creating or listening to)
  • News: news (newspapers, news aggregators, magazines, blogging, weather, etc.)
  • Photo: photography (image processing and sharing, cameras, photo management, etc.)
  • Productivity: productivity (text editors, to do list, printing, scheduling, organization and communication, calendars)
  • Security: security (antivirus, anti-malware, and firewalls)
  • Text: text (text editors, LaTeX, ViM, Emacs, word processors, etc.)
  • Tools: tools (applications that help users to accomplish a specific task, such as calculators)
  • Video: video (creating or viewing videos, subscription movie services, remote controls, etc.)

Categories

List of recommended tags:

  • end-of-life: the development was stopped. There will be no new versions of this package.

The version element

Each package version tag must have a name attribute for the version number and a package attribute that references a previously defined package. Only numeric version numbers are supported. You will have to change "1.2b" for example to "1.2.2" or similar. For beta or alpha versions the "999" prefix can be used. For example "2.55beta" can be expressed as "2.54.999.1". An attribute type can have one of the these values:

  • one-file
  • zip (default value)

Packages of type zip are normal ZIP files with arbitrary structure. It is not recommended to have a top-level directory in ZIP packages as this only creates additional sub-directory on the hard drive, but it is permitted.

Packages of the type one-file can be files of any type. They are typically used to reference .msi or .exe files, but can also be used to download a database or similar data that consists of one file.

<version name="5.10.1.1007" package="com.activestate.active-perl"
        type="one-file"> 
    <!--
        The nested tags *important-file* are used to denote important files in a package. 
        Shortcuts in the Windows start menu will be automatically created/deleted 
        if a package is installed/unistalled. The *path* and *title* attributes are 
        used to choose a file from the package and to give it an appropriate title.
        Some .exe or .msi based installations override shortcuts in the start menu
        from a different version of the same package. That is why it is sometimes
        necessary to use this tag even for such installations.
        The installation of a package will fail if the corresponding file is not
        found.
    -->
    <important-file path="ActivePerl-5.10.1.1007-MSWin32-x86.msi"
            title="Installer"/> 

    <!--
        (since 3.4/Npackd 1.22) The nested tags *cmd-file* are used to describe
        important command line programs in a package. 
        Shortcuts in the directory "%allusersprofile%\Npackd\Commands" will be 
        automatically created/deleted if a package version is 
        installed/unistalled. On Windows 7 this would be 
        "C:\ProgramData\Npackd\Commands". This directory can be added to the 
        PATH variable to make all command line tools installed via Npackd
        available from the command line. Please do not try to change the files
        in this directory as they will be overriden the next time you run 
        Npackd.
        The *path* attribute is used to choose a file from the package.
        If multiple versions of a package define a command line tool with the 
        same name, the newer version will be chosen. If multiple packages define
        a command line tool with the same name, the package with the bigger name
        will win. The package names will be compared using the Unicode code 
        points so that, e.g. "mingw-w64" will win over "mingw" or "cygwin".
        Please also note that all the links be placed in the same directory. 
        There will be no sub-directories under 
        "%allusersprofile%\Npackd\Commands".
        The installation of a package will fail if the corresponding file is not
        found.
    -->
    <cmd-file path="bin\perl.exe"/> 

    <!-- 
        Additional files placed in the package directory. See the next chapter for the in-depth explanation.
    -->
    <file path=".Npackd\Install.bat">msiexec.exe /I ActivePerl-5.10.1.1007-MSWin32-x86.msi</file>
    <file path=".Npackd\Uninstall.bat">msiexec.exe /uninstall ActivePerl-5.10.1.1007-MSWin32-x86.msi</file>
    <file path=".Npackd\Build.bat">gcc src\*.c</file>
    <file path=".Npackd\ExportUserSettings.bat">copy %appdata%\MyProgram\shortcuts.xml .</file>
    <file path=".Npackd\ImportUserSettings.bat">copy /y shortcuts.xml %appdata%\MyProgram</file>

    <!-- 
        URL where the package can be downloaded (http: or https:). The downloaded file
        is stored on the local disk under the same name as the last part of the URL.
        Example: "http://www.example.com/myfile.exe" will be stored as "myfile.exe".
        
        (since 2.1) the tag is not mandatory. Package version 
        definitions without a valid URL can only be used for detection. 
        
        (since 3.4/Npackd 1.22) the URL must not be absolute and will be 
        resolved relative to the URL of the repository.

        (since 3.6/Npackd 1.27) URLs without a file name will be downloaded to a file
        named "data"
    -->
    <url>http://downloads.activestate.com/ActivePerl/releases/5.10.1.1007/ActivePerl-5.10.1.1007-MSWin32-x86.msi</url> 

    <!-- (since 1/Npackd 1.13) SHA1 hash for the download file (optional) -->
    <sha1>68ac906495480a3404beee4874ed853a037a7a8f</sha1>

    <!-- 
        (since 3.2/Npackd 1.19) SHA-256 hash for the download file (optional).
        Please note that defining both *sha1* tag and *hash-sum* tag is not
        allowed. The type attribute may contain either *SHA-1* or *SHA-256* and
        may be missing. The default value is *SHA-256*.
    -->
    <hash-sum type="SHA-256">d32b568cd1b96d459e7291ebf4b25d007f275c9f13149beeb782fac0716613f8</hash-sum>

    <!-- 
        (since 2) a package dependency. 
        The format is ("[" | "(") <Version> "," <Version> (")" | "]").
        The square brackets [ and ] are used for inclusive bounds, round brackets ( and ) are used for
        non-inclusive bounds. The package with the name com.microsoft.Windows is
        used to express compatible Windows versions. The dependency below is equivalent to
        [Windows 2000...Windows 7). Since Npackd 1.15 also
        com.microsoft.Windows32 (only on 32-bit Windows) and
        com.microsoft.Windows64 (only on 64-bit Windows) are defined.

        (since 3) an optional "variable" tag can be used to compute the installation
        path of the dependency and store it in the environment variable
        with the specified name. This variable will only be available
        in installation and un-installation scripts in this package
        version.
    -->
    <dependency package="com.microsoft.Windows" versions="[5.00.2195, 6.1)">
        <variable>WINDOWS_PATH</variable>
    </dependency>

    <!--
        (since 2.1) optional MSI product GUID for package
        detection. This is deprecated since 3.4/Npackd 1.22 without a 
        replacement.
    -->
    <detect-msi>{1D2C96C3-A3F3-49E7-B839-95279DED837F}</detect-msi>

    <!--
        (since 2.1) package detection by SHA1 check sum of a file. If
        multiple detect-file tags are present, all files must match 
        for the package to be detected. This is deprecated since 3.4/Npackd 1.24 
        without a replacement.
    -->
    <detect-file>
        <!-- relative file path -->
        <path>ide\modules\org-netbeans-core-ide.jar</path>

        <!-- SHA1 of the file -->
        <sha1>8D244BE2B690093283138698AF5669A6861E5E20</sha1>
    </detect-file>
</version> 

The file element

(since 1/Npackd 1.10) additional files can be placed in the package directory. The whole file content is supplied between in a file tag. The path attribute is mandatory and contains a relative path where the file should be stored. This can be used e.g. to place scripts for installation and uninstallation for packages that do not follow the package format.

(since 3/Npackd 1.16) the contents is saved in UTF-8 instead of the default system encoding. Please note that .bat files are always encoded using the default platform encoding Unicode is not supported in batch files by cmd.exe, not even UTF-16. This means that you should only use ASCII characters in batch files. UTF-8 has the same internal representation as one-byte-per-character Windows encodings for ASCII characters 0 to 127. Nonetheless cmd.exe is started with the /U parameter and all input and output for the internal commands will be done using UTF-16.

(since 3/Npackd 1.16) cmd.exe is used instead of running the .bat file directly. The latter uses the command line processor associated with .bat file, which is in most cases cmd.exe. Previous versions also always ran 32-bit version of cmd.exe. Since Npackd 1.16 64-bit version is choosen on 64-bit systems. The exact parameters used are: cmd.exe /U /E:ON /V:OFF /C ""<path and name of a .bat file>""

NPACKD_CL

(since 2.1) the environment variable with the name NPACKD_CL is defined for all scripts and points to the newest installed version of com.googlecode.windows-package-manager.NpackdCL.

NPACKD_PACKAGE_NAME and NPACKD_PACKAGE_VERSION

(since 2.1) the environment variables NPACKD_PACKAGE_NAME and NPACKD_PACKAGE_VERSION are defined for all scripts and contain the full package name and version of the package currently being installed or uninstalled.

Install.bat and Uninstall.bat

(since 1/Npackd 1.10) the files ".WPM\Install.bat" and ".WPM\Uninstall.bat" in the package directory or .zip file will be called to make additional changes to the system if necessary. The batch files will be executed from the package directory (e.g. C:\Program Files\ActivePerl).

(since 2/Npackd 1.14) the files ".Npackd\Install.bat" and ".Npackd\Uninstall.bat" in the package directory or .zip file will be called to make additional changes to the system if necessary. If ".Npackd\Install.bat" exists, it is used instead of ".WPM\Install.bat". The same applies to ".WPM\Uninstall.bat". The batch files will be executed from the package directory (e.g. C:\Program Files\ActivePerl)

(since 3.1/Npackd 1.18) The environment variable NPACKD_PACKAGE_BINARY is defined during the installation for package versions of type one-file and contains the full path and file name to the downloaded binary. Example: C:\Program Files\MyPackage\MyPackageInstaller.exe

Stop.bat

(since 3.2/Npackd 1.19) the file .Npackd\Stop.bat may be included and will be called to stop a running package version. If the return code of this script is not equal to zero the package removal operation fails. If this file does not exist, the program will be stopped using default available methods like closing its windows or killing the process. The current directory for running the script is the directory where the package is installed.

Build.bat

(since 3.5/Npackd 1.26) the file .Npackd\Build.bat may be included and will be called to build another package from this one. An empty directory will be created for the output package. The directory of the installed package is passed in the environment variable NPACKD_PACKAGE_DIR to the batch script. The name of the output package is passed in the environment variable NPACKD_OUTPUT_PACKAGE. The current directory for running the script will be the output directory. If the return code of this script is not equal to zero the package build operation fails.

ExportUserSettings.bat and ImportUserSettings.bat

(since 3.6/Npackd 1.27) the file .Npackd\ExportUserSettings.bat may be included and will be called to export the user specific program settings. An empty directory be created for the output. The directory of the installed package is passed in the environment variable NPACKD_PACKAGE_DIR to the batch script. The current directory for running the script will be the output directory. If the return code of this script is not equal to zero the operation fails.

(since 3.6/Npackd 1.27) the file .Npackd\ImportUserSettings.bat may be included and be called to import the user specific program settings. The directory of the installed package is passed in the environment variable NPACKD_PACKAGE_DIR to the batch script. The current directory for running the script will be the directory with the settings. If the return code of this script is not equal to zero the operation fails.

⚠️ **GitHub.com Fallback** ⚠️