Alchemy OS Policy manual

This document describes the policy requirements for Alchemy OS distribution.

Document version: 0.6

Last edited: 2013-06-08

Contents

1 Software archive

Software for Alchemy OS is distributed in packages. The software archive is a centralized collection of these packages. To be included in software archive, package must meet the following requirements:

1.1 Archive areas

Being free software itself, Alchemy OS encourages use of free software in general. Thus, packages in software archive are split in two areas based on their licenses and other restrictions — main and nonfree. This allows users to choose what software they want to use. To be included in main area, package must meet the following additional requirements:

1.2 Free Software guidelines

These guidelines form our definition of free software. These are requirements for a package to be a part of main area of the software archive.
  1. Free Redistribution. The license of a package may not restrict any party from selling or giving away the software. The license may not require a royalty or other fee for such sale.
  2. Source Code. The program must include source code, and must allow distribution in source code as well as compiled form.
  3. Derived Works. The license must allow modifications and derived works, and must allow them to be distributed under the same terms as the license of the original software.
  4. No Discrimination Against Persons or Groups. The license must not discriminate against any person or group of persons.
  5. No Discrimination Against Fields of Endeavor. The license must not restrict anyone from making use of the program in a specific field of endeavor. For example, it may not restrict the program from being used in a business, or from being used for genetic research.
  6. Distribution of License. The rights attached to the program must apply to all to whom the program is redistributed without the need for execution of an additional license by those parties.
  7. License Must Not Be Specific to Alchemy OS. The rights attached to the program must not depend on the program's being part of an Alchemy OS.
  8. License Must Not Contaminate Other Software. The license must not place restrictions on other software that is distributed along with the licensed software.
Examples of free licenses are "GPL", "BSD" and "MIT" licenses.

2 File system hierarchy

Directory Purpose
/bin/ Executable programs and shell commands
/lib/ Shared libraries
/lib/<package>/ Private libraries, modules, plugins
/inc/ Library headers
/res/<package>/ Package resource files
/cfg/ Configuration files
/home/ User directory
/tmp/ Directory for temporary files

2.1 /bin/ directory

This directory contains programs that can be executed or used as shell commands. Package should only install executable files here (see 4.1). Other files and/or subdirectories are forbidden.

2.2 /lib/ directory

This directory contains shared libraries which can be used by several programs. All shared libraries must include API version in their name. Format of the name is 
libname.version.so
The reason for that is that there may be programs compiled with different versions of a library, so these versions should be made coinstallable. Note, that API version (or soversion) is not necessarily the same as the software version. It is common that soversion stays the same while API of the library provides remains constant. General recommendations for API versioning: Thus, libraries with different major version numbers are incompatible, programs linked against one version of the library, may not work with another. Libraries with the same major version number are backwardly compatible, libfoo.1.2.so may be used for programs linked against libfoo.1.1.so or libfoo.1.0.so.

For simple libraries it is ok to use a single number (only major part of a version).

Since there may be several versions of the library providing the same API, the soname is used to identify what to load for use by the program. To add soname to the library, use -s compiler option. For example, libfoo library may be compiled as 

ex foo.e -o libfoo.1.so -slibfoo.1.so
The soname not necessarily matches library name. For example, if libbar provides API compatible with libfoo library, it may also use soname libfoo.1.so. So, any program linked against libfoo will work if libbar installed as well.

If library name and soname differ, package must also provide a link to the library. Some package also needs to provide unversioned link to use by compiler.

Example layout:

/lib/libfoo.1.2.so Library with soname "libfoo.1.so"
/lib/libfoo.1.0.so Library with soname "libfoo.1.so"
/lib/libfoo.0.3.so Library with soname "libfoo.0.so"
/lib/libfoo.1.so Link with contents "#=libfoo.1.2.so"
/lib/libfoo.0.so Link with contents "#=libfoo.0.3.so"
/lib/libfoo.so Link with contents "#=libfoo.1.2.so"
Thus, program compiled with option -lfoo.0 will be linked against libfoo.0.3.so and program compiled with option -lfoo.1 or just -lfoo will be linked against libfoo.1.2.so.

2.3 /lib/<package>/ directory

This directory contains private package libraries, modules, plugins and programs that should not be directly executed by the user.

2.4 /inc/ directory

This directory contains header files (*.eh) for development. Library headers must either start with library name or put under /inc/<libname>/.

2.5 /res/ directory

This directory contains resource files (images, sounds, etc...). Package must install its resources under /res/<package>/.

2.6 /res/doc/ directory

This directory contains documentation files, manuals, examples. Package must install its documents under /res/doc/<package>/.

2.7 /cfg/ directory

Configuration files, program settings, etc... Packages should NOT install anything in /cfg/. Instead, create configs on the first launch of your program. Configuration files must either start with program or stored under /cfg/progname/.

2.8 /home/ directory

User directory. Packages must NOT install anything in it.

2.9 /tmp/ directory

Directory for temporary files. Packages must NOT install anything in it.

3 Format of the source package

Source package is a zip archive with program sources and metadata. Metadata must be stored in a file with .package extension. The package file consists of several paragraphs. The first paragraph describes source package, the following are specifications of binary packages that are produced from it. Each paragraph is a set of lines of the form 
Field: Value
Value of the field may span several lines, in this case second and subsequent lines must start with a space. Metadata file can also contain commentary lines starting with # character.

An example of the source package metadata file. 

# The first paragraph gives program
# classification and legal stuff
Source: foobar
Section: utils
Version: 1.2
Author: John Foo
Maintainer: Ryan Bar <ryan.bar@example.com>
Copyright: (c) 2013 Foobar developers
License: GPL-3
Build-Depends: make, barfoo

# This is the first package produced from the source
Package: foo
Summary: Utility that does good things.
Depends: zip

# Another package built from this source
# Note that it belongs to another section
Package: bar
Section: misc
Summary: Utility that does evil things.
 Use with care and negate its effects with 'foo' afterwards.
Depends: ${libdeps},  bf

Fields that can be defined in the first paragraph:

Field Description
Source Name of the source package.
Version Software version.
Section Classification of software.
Copyright Copyright holder of the software.
Author Author of the software.
Maintainer Maintainer of the package.
License License of the software.
Homepage URL to the project home page.
Build-Depends List of packages that are needed for building.

Fields that can be defined in subsequent paragraphs:

Field Description
Package Name of the binary package.
Summary Short description.
Depends List of package dependencies.
Additionally, binary package may override any of the following fields: Version, Section, Copyright, Author, Maintainer, License, Homepage.

3.1 Source field

This field is the name of the source package. Valid characters in the name are lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). It must be at least two characters long and must start with an alphanumeric character.

Package name should not be too generic (like book, help or compiler). Be creative, or at least add author's name to the name (john-book, john-compiler).

3.2 Version field

The version number of a package. The version may contain only alphanumerics and the characters . + - ~ and must start with a digit.

Versions are compared using the following algorithm:

  1. First, the leftmost numeric parts are compared as numbers.
  2. If those numbers are equal, subsequent string parts (until the next number) are compared lexicographically. The character ~ has a special meaning − it sorts before any other character, even before empty string.
  3. If string parts are equal, the first two steps are repeated for the remainder of the string.
For example, the following relations hold: 
2.3~pre1  <  2.3  ==  2.03  <  2.4

3.3 Section field

This field specifies an application area into which the package has been classified.

At present, sections are:

Section Description
admin Administrative utilities.
devel Development tools.
doc Documentation and programs to read it.
graphics Programs that work with images.
games Games and entertaining programs.
gui Graphical interface.
libdevel Development headers for libraries.
libs Libraries of functions, for use by other programs.
net Web-browsers, mail clients, downloaders, etc.
sound Programs that work with sound.
text Text editors and processors.
utils Utilities to work with files, backup tools, archivers, etc.
video Programs that work with video.
misc Miscellaneous software, if nothing of the above is applicable.
Other sections may be added by request.

3.4 Copyright field

The copyright notice, typically the name of the holder of the copyright on the package and the year from which copyright is claimed. For example: 
Copyright: (c) 2012-2013 John Doe

3.5 Author field

The name of the author of the software. If you are the author and want to receive bug reports, feature requests and/or patches for your software you may also specify your e-mail. Preferred format: 
Author: Your Name <your@email>

3.6 Maintainer field

Maintainer of the package. Specify this field if you are not the author of the software, but provide packaging for it. Format is the same as of the Author field.

3.7 License field

The license under which this package is distributed. Freeform field, but preferrably one of the following constants.
Constant Description
GPL-2,
GPL-3 		GNU General Public License, 2.0, 3.0. Requires all derivatives to be under the same license.
GPL-3+exception GNU General Public License with runtime linkage exception. This is the license of system libraries of Alchemy OS (see here).
LGPL-2.1,
LGPL-3 		Lesser GNU General Public License, 2.1, 3.0. Useful for libraries.
BSD-3 Berkeley Software Distribution license, (3-clause).
BSD-2 Simplified Berkeley Software Distribution license, (2-clause).
MIT The MIT license, similar to BSD-3.
PublicDomain No license required for any purpose; the work is not subject to copyright in any jurisdiction.
OtherOpenSource Open source license not in above list. It is better to specify one of SPDX identifiers instead.
AllRightsReserved If package is distributed under non-free license. In this case, full text of the license must be included in the package under /res/doc/licenses/<package>.txt

3.8 Homepage field

The URL of the web site for the software, if any.

3.9 Build-Depends field

Comma-separated list of packages that are required to build binary packages from this source. This list NEED NOT to include pkgbuild, ex, libcore-dev and libui-dev as well as any packages which are provided by alchemy-core.

3.10 Package field

This field is the name of the binary package. Restrictions on the name are the same as in Source field.

3.11 Summary field

This field contains short description of the package.

3.12 Depends field

Comma-separated list of packages that are needed for this package to function properly.

4 Format of the binary package

Alchemy OS binary package is an arh archive. It stores all files of the software preserving directory structure, and a file with the package metadata named PACKAGE. The PACKAGE file must be the first entry in the archive.

The PACKAGE file uses the same format as for the source package metadata file, but consists of the single paragraph and may contain the following fields: Package, Version, Summary, Section, Depends, Copyright, Author, Maintainer, License, Homepage, Source.

5 Library packages

There should be discretion between the runtime files including library itself and files it needs to work, and the development files that are needed to compile programs with support of that library. If some package only depends on the library to work, it does not need the development files. Thus, runtime and development files should be split in distinct packages.

5.1 Runtime package

Runtime library package should be named as lib<name><soversion>. For example, package for libfoo.1.2.so should be named libfoo1. Since libraries with the same major version number are backwardly compatible there is no generally need to keep older version like libfoo.1.0.so in software archive, so minor version number in package name is not needed. If there is such need, however, packages should be called libfoo1.0 and libfoo1.2 respectively.

The section field of the library package must be set to "libs".

5.2 Development package

Development package containing library headers should be named as lib<name>-dev and be in section "libdevel". If besides headers, package provides some binary tools, it should be named <name>-dev and put in "devel" instead.

Development package must depend on the corresponding runtime library package and provide an unversioned link for the compiler.

If you want to provide different development packages for different library versions, you may use versioned names for them, like libfoo0-dev and libfoo1-dev. There should be then unversioned package libfoo-dev depending on the default version and providing unversioned link.

5.3 Library resources

Care should be taken if library package installs some resource files. To make different versions of the library coinstallable you must install resource files in versioned directories as well (/res/libfoo0/, /res/libfoo1/ and so on). If different versions of library use the same resources, however, duplicating these files is a waste of space. Instead, you may create package libfoo-common containing these resource files and make library packages depend on it.
Copyright (c) 2012-2013, Sergey Basalaev

This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

This is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available on the World Wide Web (see http://www.gnu.org/copyleft/gpl.html). You can also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.