bento.info format reference

Introduction

The package description is a text file, by default named bento.info. Its syntax is indentation-based. It does not support yet commenting, and is currently limited to ASCII.

A typical .info file is structured as follows:

  • The package metadata (name, version, etc...)
  • Optionally, it may contain addition user-customizable options such as path or flags, whose exact value may be set at configure time.
  • A Library section, which defines the package content (packages, modules, C extensions, etc...)
  • Optionally, the .info file may contain one or several Executable sections, to describe programs expected to be run from the command line or from a GUI. This is where distutils scripts and setuptools console scripts are defined.

Each section consists of field:value pairs:

  • Both fields and values are case-sensitive.
  • Indentation has to be in spaces, tab characters for indentation are not supported. Besides this constraints, rules for indentation should follow python’s own rule (arbitrary number of spaces for a given indentation level).

Package metadata

Bento supports most metadata defined in the PEP 241 and 314. For a simple package containing one module hello, the bento.info metadata definition would look like:

Name: hello
Version: 0.0.1
Summary: A one-line description of the distribution
Description:
    A longer, potentially multi-line string.

    As long as the indentation is maintained, the field is considered as
    continued.
Author: John Doe
AuthorEmail: john@doe.org
License: BSD

Different fields have different values: they generally consist of either a word (string sequence without a space), a line (a sequence of words without a newline) or multiple lines (Description field only).

Note:: while most metadata defined in the PEP-241 and PEP-314 are supported syntax-wise, their semantics are not always implemented already.

Note:: the bento lexer is ad-hoc and not well specified at this stage. It was conceived to handle values in the reStructuredText format, but doing so prevents desired flexibility of the bento.info format itself, or would be too complex to support. Before 1.0, bento.info format may change so that fields in reStructuredText need to be put in a separate file, e.g.:

DescriptionFromFile: README.rst

If you are reading this and actually know something about parsing and have a better idea to support inline reST, I am open to suggestions !

Name

Format:

Name: ASCII_TOKEN

Name of the software being packaged. Its value should contain only alpha-numeric characters.

Version

Format:

Version: VERSION_TOKEN

VERSION_TOKEN format is not enforced yet

Summary

Format:

Description: WORDS

One or more space separated words

Url

Author

Author email

Maintainer

Maintainer email

License

Description

Platforms

Classifiers

User-customizable flags

Library section

Executable section

Pure python packages

Assuming a package with the following layout:

hello/pkg1/__init__.py
hello/pkg1/...
hello/pkg2/__init__.py
hello/pkg2/...
hello/__init__.py

it would be declared as follows:

Name: hello
Version: 0.0.1

Library:
    Packages:
        hello.pkg1,
        hello.pkg2,
        hello

The following syntax is also allowed:

Library:
    Packages:
        hello.pkg1, hello.pkg2, hello

as well as:

Library:
    Packages: hello.pkg1, hello.pkg2, hello

Packages containing C extensions

For a simple extension hello._foo, built from sources src/foo.c and src/bar.c, the declaration is as follows:

Library:
    Extension: hello._foo
        Sources:
            src/foo.c,
            src/bar.c

Note: none of the other distutils Extension arguments (macro definitions, etc...) are supported yet.

Packages with data files

Adding data files in bento is easy. By data files, we mean any file other than C extension sources and python files. There are two kinds of data files in bento:

  • Installed data files: those are installed somewhere on the user system at installation time (distutils package_data and data_files, numpy.distutils add_data_files and add_data_dir).
  • Extra source files: those are only necessary to build the package, and are not installed. As such, they only need to be included in the source tarball (distutils MANIFEST[.in] mechanism, automatic inclusion from the VCS in setuptools, etc...)

Extra source files

Extra source files are simply declared in the section ExtraSourceFiles (outside any Library section):

ExtraSourceFiles:
    AUTHORS,
    CHANGES,
    EXAMPLES,
    LICENSE,
    Makefile,
    README,
    TODO,
    babel.cfg

Those will be always be included in the tarball generated by bento sdist. A limited form of globbing is allowed:

ExtraSourceFiles:
    doc/source/*.rst
    doc/source/chapter1/*.rst

that is globbing on every file with the same extension is allowed. Any other form of globbing, in particular recursive ones are purposedly not supported to avoid cluttering the tarball by accident.

Installed data files

It is often needed to install data files within the rest of the package. Bento’s system is both simple and flexible enough so that any file in your sources can be installed anywhere. The most simple syntax for data files is as follows:

DataFiles:
    TargetDir: /etc
    Files:
        somefile.conf

This installs the file somefile.conf into /etc. Using hardcoded paths should be avoided, though. Bento allows you to use “dynamic” path instead. This scheme should be familiar to people who have used autotools:

DataFiles:
    TargetDir: $sysconfdir
    Files:
        somefile.conf

$sysconfigdir is a path variable: bento defines several path variables (available on every platform), which may be customized at the configure stage. For example, on Unix, $sysconfdir is defined as $prefix/etc, and prefix is itself defined as /usr/local. If prefix is changed, sysconfdir will be changed accordingly. Of course, sysconfdir itself may be customized as well. This allows for very flexible installation layout, and every particular install scheme (distutils –user, self-contained as in GoboLinux or Mac OS X) may be implemented on top.

It is also possible to define your own path variables (see Path option section).

Srcdir field

By default, the installed name is the concatenation of target and the values in files, e.g.:

DataFiles:
    TargetDir: $includedir
    Files:
        foo/bar.h

will be installed as $includedir/foo/bar.h. If instead, you want to install foo/bar.h as $includedir/bar.h, you need to use the srcdir field:

DataFiles:
    TargetDir: $includedir
    SourceDir: foo
    Files:
        bar.h

Named data files section

You can define as many DataFiles sections as you want, as long as you name them, i.e.:

DataFiles: man1
    TargetDir: $mandir/man1
    SourceDir: doc/man
    Files:
        *.1

DataFiles: man3
    TargetDir: $mandir/man3
    SourceDir: doc/man
    Files:
        *.3

is ok, but:

DataFiles:
    TargetDir: $mandir/man1
    SourceDir: doc/man
    Files:
        *.1

DataFiles:
    TargetDir: $mandir/man3
    SourceDir: doc/man
    Files:
        *.3

is not.

Available path variables

By default, bento defines the following path variables:

  • prefix: install architecture-independent files
  • eprefix: install architecture-dependent files
  • bindir: user executables
  • sbindir: system admin executables
  • libexecdir: program executables
  • sysconfdir: read-only single-machine data
  • sharedstatedir: modifiable architecture-independent data
  • localstatedir: modifiable single-machine data
  • libdir: object code libraries
  • includedir: C header files
  • oldincludedir: C header files for non-gcc
  • datarootdir: read-only arch.-independent data root
  • datadir: read-only architecture-independent data
  • infodir: info documentation
  • localedir: locale-dependent data
  • mandir: man documentation
  • docdir: documentation root
  • htmldir: html documentation
  • dvidir: dvi documentation
  • pdfdir: pdf documentation
  • psdir: ps documentation

While some of those path semantics don’t make sense on some platforms such as windows, they are defined everywhere with defaults, to ensure a consistent interface across platforms. They are also defined to to get a 1-to-1 correpondance with the autoconf conventions, which are familiar to most packagers on open source OS and system administrators.

Conditionals

It is not always possible to have one same package description for every platform. It may also be desirable to enable/disable some parts of a package depending on some option. For this reason, the .info file supports a limited form of conditional. For example:

Library:
    InstallRequires:
        docutils,
        sphinx
        if os(windows):
            pywin32

The following conditional forms are available:

  • os(value): condition on the OS
  • flag(value): user-defined flag, boolean

Adding custom options

Path option

A new path option may be added:

Path: octavedir
    Description: octave directory
    Default: $datadir/octave

Bentomaker automatically adds an –octavedir option (with help taken from the description), and $octavedir may be used inside the .info file.

Flag option

A new flag option may be added:

Flag: debug
    Description: build debug
    Default: false

Bentomaker automatically adds an –octavedir option (with help taken from the description), and $octavedir may be used inside the .info file.