Skip to content

Folders

Hervé Bitteur edited this page Jan 24, 2018 · 5 revisions

This section summarizes the various folders used by Audiveris 5.1 version.

Precise location sometimes depends on the operating system but more importantly on the folder purpose:

Development folder

The Clone, Build & Run approach consists in cloning the remote GitHub Audiveris repository into a local repository on your machine:

git clone https://github.com/Audiveris/audiveris.git

By default, this creates a sub-folder named "audiveris" in your current folder, and downloads the remote repository into path/to/your-current-folder/audiveris.

You can explicitly choose a different target folder (if it already exists, it must be empty) by using this other cloning command:

git clone https://github.com/Audiveris/audiveris.git specific-target-folder

Explicit or implicit, this local repository folder will now be referred to as the development folder, because the various development tasks (such as gradle build or gradle run) will need to be issued from this folder.

The gradle run command, or some derived command, can be used to launch the application.

Installation folder

As explained in the optional installation procedure, you have the ability to expand the content of an Audiveris distribution archive (which you built as part of the gradle build) into a folder of your choice.

This installation folder will then contain two sub-folders:

  • bin with two command files, Audiveris and Audiveris.bat, meant to launch the application from UN*X and Windows respectively.
  • lib with a bunch of 127 (as of this writing) .jar binary files used by the application.

User folders

While a developer could modify or add material in the development folder, from a user point of view, both the development folder and the installation folder should be considered as read-only locations.

Then, for any file that a user would have full control upon, the Audiveris application defines by default three dedicated locations:

  • a config folder meant for user configuration information,
  • a data folder for any other kind of user data,
  • a log folder for Audiveris log files.

Config folder

Content:

  • run.properties where user-modified values of application constants are automatically persisted.
  • logback.xml to customize the general logging mechanism.
  • user-actions.xml to include additional actions in UI top menus.
  • plugins.xml to define how to launch external music editors on user machine.

Data folder

Content:

  • output folder. This is the default output base folder. We call it a base, because all the outputs of a given input myScore.pdf are stored in a dedicated myScore/ sub-folder of this output base.
    This default output base can be superseded by:

    • the use of -output "my-specific-base" option on the command line,
    • the customization of application constant org.audiveris.omr.sheet.BookManager.baseFolder
  • train folder. This is where user-initiated sampling and classifier training store their data.

  • etc...

Log folder

Content:

Just the log files written by runs of Audiveris application.

The name of a log file is based on current date and time, formatted as "yyyyMMdd'T'HHmm", resulting in file name such as 20170804T075002.log

User folders locations

Windows

Windows defines a user environment variable APPDATA which generally translates as C:\Users\your-name\AppData.

  • config: %APPDATA%\Roaming\AudiverisLtd\audiveris\config
  • data: %APPDATA%\Roaming\AudiverisLtd\audiveris\data
  • log: %APPDATA%\Roaming\AudiverisLtd\audiveris\log

Linux

If your Linux environment supports the XDG specifications, user folders will preferably use the proper XDG environment variables. Otherwise they will be defined with respect to your home folder.

  • config: ${XDG_CONFIG_HOME}/AudiverisLtd/audiveris
    fall-back: ~/.config/AudiverisLtd/audiveris
  • data: ${XDG_DATA_HOME}/AudiverisLtd/audiveris
    fall-back: ~/.local/share/AudiverisLtd/audiveris
  • log: ${XDG_CACHE_HOME}/AudiverisLtd/audiveris/log
    fall-back: ~/.cache/AudiverisLtd/audiveris/log

MacOS

On MacOS, Audiveris user folders are defined with respect to your home environment.

  • config: ${HOME}/Library/Application Support/AudiverisLtd/audiveris
  • data: ${HOME}/Library/AudiverisLtd/audiveris/data
  • log: ${HOME}/Library/AudiverisLtd/audiveris/log