Manual

Tip: Have a look at sysdirs.installer.BaseInstaller

sysdirs wraps the specifications in sysdirs.specifications.DirectorySpecification subclasses providing methods and properties to access directories with purpose.

The supported directory layout specifications provide more locations to store specific files but that is not in the scope of this library! One option is to let users configure all other paths in your configuration file.

Layout Comparison

  XDG FHS
config $XDG_CONFIG_HOME /etc
get_config_dirs() $XDG_CONFIG_HOME, $XDG_CONFIG_DIRS /etc
data $XDG_DATA_HOME /usr/local/share
get_data_dirs() $XDG_DATA_HOME, $XDG_DATA_DIRS /usr/local/share, /usr/share
cache $XDG_CACHE_HOME /var/cache
var $XDG_DATA_HOME /var/lib
run $XDG_RUNTIME_HOME /var/run (/run if hier is disabled)
log $XDG_CACHE_HOME /var/log

XDG

sysdirs.specifications.XDG

https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

The provided sysdirs.installer.Installer uses XDG by default!

XDG environment variables come with sane defaults in case the user is not using them.

  • XDG_CONFIG_HOME: $HOME/.config
  • XDG_CONFIG_DIRS: /etc/xdg
  • XDG_DATA_HOME: $HOME/.local/share
  • XDG_DATA_DIRS: /usr/share:/usr/local/share
  • XDG_CACHE_HOME: $HOME/.cache
  • XDG_RUNTIME_HOME: tempfile.gettempdir()

Note

A warning will be written to stderr if XDG_RUNTIME_HOME is not set!

XDG_CONFIG_DIRS and XDG_DATA_DIRS may be lists of paths divided by :.

installer = Installer('my_project')

When using sysdirs.installer.BaseInstaller you need to add the specification:

class MyInstaller(BaseInstaller):
    specifications = [
        XDG()
    ]

FHS

sysdirs.specifications.XDG

https://wiki.linuxfoundation.org/lsb/fhs

FHS provides directories like /etc, /usr and /var which are only available for installation when running as root!

To allow users to use it you need to add the specification:

installer = Installer('my_project', specifications=[FHS()])

# or:

class MyInstaller(BaseInstaller):
    specifications = [
        FHS()
    ]

Installer Exmaple

class MyInstaller(BaseInstaller):

    specifications = [
        FHS(force=True),  # force=True will prevent the selection dialog and use fhs automatically
        XDG(),
        DevDir(__file__)  # dev/ dir beside this file
    ]

    multiple_installations = False

    config_mode = 0o700
    var_mode = 0o700

    def install(self, specification=None):
        dirs = super(MyInstaller, self).install(specification=specification)

        dirs.install_config(os.path.join('contrib', 'config', basename), relpath='config.ini')
        dirs.install_data(os.path.join('contrib', 'data', 'logo.jpg'))
        dirs.install_data(os.path.join('contrib', 'data', 'some.dll'), mode=0o750)

        # create and chown directories
        dirs.install_var()
        dirs.install_log()