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).
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 !
Format:
Name: ASCII_TOKEN
Name of the software being packaged. Its value should contain only alpha-numeric characters.
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
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.
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 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.
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).
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
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.
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.
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
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.
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.