This tutorial will guide you through the basics to package your python code with bento. Note that for an existing project using setup.py-based packaging, you should look at the convert command so that you don’t have to start from scratch.
First, let’s assume you have a simple software fubar consisting of a single python module hello.py:
hello.py
A simple bento.info file would look as follows:
Name: fubar
Author: John Doe
Summary: a simple module
Library:
Modules: hello
The indentation must be done through spaces (tabs are considered syntax errors). The bento.info is located just next to your hello.py:
hello.py
bento.info
That’s it, you have your first bento package !
Currently, the only way to interact with bento is bentomaker, a command-line interface to bento. It is used to build, install and test packages from the command line:
bentomaker install
This will automatically run the configure and build commands for you. You can run them explicitely if you to customized installation, e.g.:
bentomaker configure --prefix=/blabla
bentomaker install
You can also build eggs, source tarballs and windows installers (windows only for now):
bentomaker sdist
bentomaker build_egg
bentomaker build_wininst
You can access the list of available commands with the help command:
bentomaker help commands
Adding a package (a directory with a __init__.py file) is simple as well. Assuming the following source tree:
hello.py
foo/__init__.py
foo/bar.py
You simply write:
Library:
Packages: foo
Multiple packages are specified through a comma separated list, and respect indentation:
Library:
Packages: foo, bar
or:
Library:
Packages:
foo, bar
or:
Library:
Packages:
foo,
bar
Besides packages and modules, you may want to add extra files, like configuration, manpages, documentation, etc... Those are called data files. Bento has a simple but powerful way to install arbitrary data in arbitrary locations.
Bento makes the distinction between the two following categories:
- installed files (data files): those files are part of the installed package
- extra source files: those files are not installed, but part of the source distribution. They may be README, or additional files necessary to build the software.
An extra source file will only be included in the source tarballs, whereas data files are installed and needed to use the software.
Say our fubar software has one manpage fubar.1:
fubar.1
We need to add the following to bento.info:
DataFiles: manpage
TargetDir: $mandir
Files: fubar.1
This will install the file fubar.1 into $mandir (as $mandir/fubar.1). $mandir is expanded by bento to a sensible default on every support platform, and can be customized at configuration time through the –mandir option. You can of course hardcode the install directory, e.g.:
DataFiles: manpage
TargetDir: /usr/share/man/man1
Files: fubar.1
but this is generally not recommended as it is not portable and makes native packaging more difficult. Bento has a simple mechanism so that you can add your own paths.
Extra source files are added through the ExtraSourceFiles section:
ExtraSourceFiles:
setup.py
test/*.py
Extension (compiled python modules) are supported as well. If you have an extension _hello built from the file hellomodule.c, you just write:
Library:
Extension: _hello
Sources: hellomodule.c
Similarly, if you have a compiled library (a C library which is not importable from python):
Library:
CompiledLibrary: foo
Sources: foo.c
Note that there is only one Library section, i.e. a package with both extensions and compiled libraries would look like:
Library:
Extension: _hello
Sources: hellomodule.c
CompiledLibrary: foo
Sources: foo.c
and not like:
Library:
Extension: _hello
Sources: hellomodule.c
Library:
CompiledLibrary: foo
Sources: foo.c
Note that it is currently not possible to link an extension against such a compiled library purely from the bento.info file: you need to use the hook mechanism.
Many python softwares are libraries, and their only use is from a python interpreter. Nevertheless, it is relatively common to provide a full program, be it GUI or command line tool. Bento uses a feature similar to setuptools to help you create “entry points” which work on both unix and windows systems:
Executable: foomaker
Module: foomakerlib.foomaker
Function: main
This tells bento to create a script called foomaker (foomaker.exe on windows), which calls the main function from the foomakerlib.foomaker python module. Those scripts are automatically installed in $bindir (which translates to /usr/local/bin by default on unix, and C:Python*Scripts on windows, both values which may be changed by the user at the configure stage through the –bindir option).