<commit_before>======
Guides
======

Specifiying data files
======================

Most packages have some files besides pure code: configuration, data
files, documentation, etc... When those files need to be installed,
you should use DataFiles sections. Each such section has two mandatory
fields, to specify the target directory (where files are installed)
and which files are specific to this section::

    DataFiles: manage
        TargetDir: /usr/man/man1
        Files: fubar/fubar1

This will install the file top_dir/fubar/fubar1 into
/usr/man/man1/fubar/fubar1.

Flexible install scheme
-----------------------

Hardcoding the target directory as above is not flexibe. The user may
want to install manpages somewhere else. Bento defines a set of
variable paths which are customizable from bentomaker, with platform-specific
defaults. For manpages, the variable is mandir::

    DataFiles: manpage
        TargetDir: $mandir/man1
        Files: fubar/fubar.1

Now, the installation path is customizable, e.g.::

    bentomaker configure --mandir=/opt/man

will cause the target directory to translate to /opt/man/man1.
Moreover, as mandir default value is defined relatively to $prefix ($prefix/man
on unix), modifying the prefix will also change how mandir is expanded at
install time::

    # $mandir is automatically expanded to /opt/man
    bentomaker configure --prefix=/opt

If you do not want to install files with their directory component,
you need to use the SourceDir option::

    DataFiles: manpage
        TargetDir: $mandir
        SourceDir: fubar
        Files: fubar.1

will install fubar/fubar.1 as $mandir/fubar.1 instead of
$mandir/fubar/fubar.1.

Custom data paths
-----------------

While the default list should cover most package needs, it is sometimes useful
to define custom path variable::

    Path: foo
        Description: foo directory
        Default: $datadir/foo

Bentomaker will automatically add the --foodir option, and $foo will be
expanded to the customized value (or $datadir/foo by default). The description
will be used as a description in the help message.

Retrieving data files at runtime
================================

It is often necessary to retrieve data files from your python code.  For
example, you may have a configuration file which needs to be read at startup.
The simplest way to do so is to use __file__ and refer to data files relatively
to python code location. This is not very flexible, because it requires dealing
with platform idiosyncraties w.r.t. file location.  Setuptools and its<commit_msg>DOC: basic doc for conditional path customization.<commit_after>======
Guides
======

Specifiying data files
======================

Most packages have some files besides pure code: configuration, data
files, documentation, etc... When those files need to be installed,
you should use DataFiles sections. Each such section has two mandatory
fields, to specify the target directory (where files are installed)
and which files are specific to this section::

    DataFiles: manage
        TargetDir: /usr/man/man1
        Files: fubar/fubar1

This will install the file top_dir/fubar/fubar1 into
/usr/man/man1/fubar/fubar1.

Flexible install scheme
-----------------------

Hardcoding the target directory as above is not flexibe. The user may
want to install manpages somewhere else. Bento defines a set of
variable paths which are customizable from bentomaker, with platform-specific
defaults. For manpages, the variable is mandir::

    DataFiles: manpage
        TargetDir: $mandir/man1
        Files: fubar/fubar.1

Now, the installation path is customizable, e.g.::

    bentomaker configure --mandir=/opt/man

will cause the target directory to translate to /opt/man/man1.
Moreover, as mandir default value is defined relatively to $prefix ($prefix/man
on unix), modifying the prefix will also change how mandir is expanded at
install time::

    # $mandir is automatically expanded to /opt/man
    bentomaker configure --prefix=/opt

If you do not want to install files with their directory component,
you need to use the SourceDir option::

    DataFiles: manpage
        TargetDir: $mandir
        SourceDir: fubar
        Files: fubar.1

will install fubar/fubar.1 as $mandir/fubar.1 instead of
$mandir/fubar/fubar.1.

Custom data paths
-----------------

While the default list should cover most package needs, it is sometimes useful
to define custom path variable::

    Path: foo
        Description: foo directory
        Default: $datadir/foo

Bentomaker will automatically add the --foodir option, and $foo will be
expanded to the customized value (or $datadir/foo by default). The description
will be used as a description in the help message.

Conditional customization
^^^^^^^^^^^^^^^^^^^^^^^^^

It is sometimes necessary to define platform-specific default for custom paths.
This can be done as follows::

    Path: foo
        Description: foo directory
        if os(darwin):
            Default: /Library/foo
        else:
            Default: $bin/foo

FIXME: refer to conditional

Retrieving data files at runtime
================================

It is often necessary to retrieve data files from your python code.  For
example, you may have a configuration file which needs to be read at startup.
The simplest way to do so is to use __file__ and refer to data files relatively
to python code location. This is not very flexible, because it requires dealing
with platform idiosyncraties w.r.t. file location.  Setuptools and its
{'fraction_non_alphanumeric': 0.09158371040723982, 'fraction_numerical': 0.0043438914027149325, 'mean_word_length': 3.4890333062550773, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2446427', 'n_tokens_mistral': 1478, 'n_tokens_neox': 1435, 'n_words': 710}