Skip to content

Reword installation pages in the documentation for better clarity #842

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MaxwellBuchholz wants to merge 3 commits into
base: development
Choose a base branch
from
Open

Reword installation pages in the documentation for better clarity #842

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2ed3aaa
Reword Installation README for clarification
MaxwellBuchholz Sep 17, 2025
ecffb2d
Reword Building from sources page for readability and clarification
MaxwellBuchholz Sep 17, 2025
e65fdff
Reword Installing from Binaries page for readability and clarity
MaxwellBuchholz Sep 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions docs/_pages/tutorials/install/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,15 @@ nav_order: 1
new in 5.5
{: .label .label-yellow }

For **Windows**, **macOS** and **Linux**, Audiveris provides installers available in 64-bit version.
A 64-bit installer is provided for **Windows**, **macOS** and **Linux**.

An installer simplifies installation but has the main disadvantage of being limited
to the latest official version, which may be several months old.

## Building from sources
## Building from source

For **Windows**, **macOS**, **Linux** and **ArchLinux**,
you have the ability to **clone and build** from the source material.

The main advantage is to benefit from all the bug fixes and improvements that are
continuously published on the Audiveris project site in its "development" branch.
For **Windows**, **macOS** and **Linux**,
you have the ability to **clone and build** from the source code.

The main advantage of doing this is to benefit from all the bug fixes and improvements that are
continuously published in the "development" branch of the Audiveris project.
104 changes: 51 additions & 53 deletions docs/_pages/tutorials/install/binaries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
layout: default
title: Installing binaries
title: Installing from binaries
nav_order: 2
parent: Installation
---
# Installing binaries
# Installing from binaries
{: .no_toc }

---
Expand All @@ -18,18 +18,18 @@ Table of contents
new in 5.5
{: .label .label-yellow }

Since version 5.5, Audiveris provides installers for Windows, for Linux and for macOS.
Since version 5.5, Audiveris has provided installers for Windows, Linux and macOS.

These installers are based on the same structure:
1. The application comes with its own Java Runtime Environment (JRE).
1. The application comes with its own Java Runtime Environment (JRE).
Therefore, there is no need for the user to install a specific JRE.
2. The application comes with *no* pre-installed OCR languages,
but offers a [runtime dialog box](../../guides/main/languages.md) allowing the user to install
any desired OCR language(s).
any desired OCR language(s).
The application is then responsible for picking up the right version of the language files
on the Tesseract site and for installing them in the user environment.

The installers files can be downloaded from the assets of a recent release
The installers can be downloaded from the assets section of a recent release
available on the Audiveris [releases page](https://github.com/Audiveris/audiveris/releases).

The name of each installer file is formatted as:
Expand Down Expand Up @@ -62,52 +62,50 @@ Remarks:
- One without console, which displays just the graphic user interface. This is the recommended variant.
- One with console, where a Terminal window is launched together with the graphic user interface.
This variant can be useful to display error messages.
- The **PDF** version of the Audiveris **handbook** can be useful if you don't have a permanent Internet access,
since its content is identical to the [online version](https://audiveris.github.io/audiveris/).
- The **PDF** version of the Audiveris **handbook** can be useful if you don't have permanent Internet access,
as its content is identical to the [online version](https://audiveris.github.io/audiveris/).
- The **Schemas_Doc** is meant for the developers. It documents the entities `Book`, `Sheet` and `PlayList` which compose the Audiveris `.omr` project files.

The downloaded installer file will be used to install the application in the target OS,
The downloaded installer file will be used to install the application in the target OS,
as detailed in the following sections.

{: .note :}
Once the application is launched, OCR languages can be downloaded directly from within the Audiveris application.
See the [OCR languages](../../guides/main/languages.md) section.

Beside these installers, Audiveris used to provide an additional installer
-- actually a **Linux/Flatpak** package -- also with a suitable JRE included.
This package can be installed directly from the
[Flathub](https://flathub.org/apps/org.audiveris.audiveris) site.
However, the future of this Flatpak package is not clear, for lack of skill and/or manpower.
Audiveris used to provide a **Linux/Flatpak** package which can be installed directly from the
[Flathub](https://flathub.org/apps/org.audiveris.audiveris) site.
However, the future of this Flatpak package is not clear, due to a lack of skill and/or manpower.


## Windows installer
## Windows

### Installation

Double-click the `Audiveris-<version>-windows-x86_64.msi` file in your `Downloads` folder (or wherever it’s saved).

| Action | Dialog |
| :--- | :--- |
| A double-click has opened the `Audiveris Setup` dialog box | ![](../../assets/images/windows_install.png) |
| The license agreement is displayed. If you agree, tick the checkbox and then click on `Next`| ![](../../assets/images/windows_license.png) |
| The default installation folder can be changed | ![](../../assets/images/windows_install_folder.png) |
| By default, the installer creates one shortcut on the desktop and one shortcut in the Windows start menu | ![](../../assets/images/windows_shortcuts.png) |
| The installation is now launched| ![](../../assets/images/windows_install_do.png) |
| You may get an alert from Windows user account control, since Audiveris is not from a "known" publisher. Click on `Yes` to allow.| ![](../../assets/images/windows_uac.png) |
| The installation is finished| ![](../../assets/images/windows_install_finish.png) |
| Action | Dialog |
| :--- | :--- |
| A double-click has opened the `Audiveris Setup` dialog box | ![](../../assets/images/windows_install.png) |
| The license agreement is displayed. If you agree, tick the checkbox and then click on `Next` | ![](../../assets/images/windows_license.png) |
| The default installation folder can be changed if desired | ![](../../assets/images/windows_install_folder.png) |
| By default, the installer creates a shortcut on the desktop and one in the Windows start menu | ![](../../assets/images/windows_shortcuts.png) |
| The installation is now ready | ![](../../assets/images/windows_install_do.png) |
| You may get an alert from Windows User Account Control, since Audiveris is not from a "known" publisher. Click on `Yes` to allow. | ![](../../assets/images/windows_uac.png) |
| The installation is finished | ![](../../assets/images/windows_install_finish.png) |

### Running

The application can be launched in different ways:
The application can be launched in a variety of ways:

| Way | Illustration |
| :--- | :--- |
|Opening the Windows **start menu** and selecting the Audiveris item | ![](../../assets/images/windows_start_menu.png) |
| Double-clicking on the Audiveris icon located on Windows **desktop** | ![](../../assets/images/windows_desktop_shortcut.png) |
| Double-clicking on a **`.omr` file**, since the `.omr` file extension (which represents a Book) has been associated with Audiveris application | ![](../../assets/images/windows_book_file.png) |
| In a terminal window, entering a **command** refering to the program location | "C:\Program Files\Audiveris\Audiveris.exe" `<potential arguments>` |
| Action | Illustration |
| :--- | :--- |
| Opening the Windows **start menu** and selecting the Audiveris icon | ![](../../assets/images/windows_start_menu.png) |
| Double-clicking on the Audiveris icon located on Windows **desktop** | ![](../../assets/images/windows_desktop_shortcut.png) |
| Double-clicking on a **`.omr` file**, since the `.omr` file extension (which represents a Book) is associated with the Audiveris application | ![](../../assets/images/windows_book_file.png) |
| In a terminal window, entering a **command** refering to the program location | "C:\Program Files\Audiveris\Audiveris.exe" `<potential arguments>` |

The very first time Audiveris is launched, the anti-virus software may get in the way:
The very first time Audiveris is launched some anti-virus software may get in the way:

| Event | Illustration |
| :--- | :--- |
Expand All @@ -116,7 +114,7 @@ The very first time Audiveris is launched, the anti-virus software may get in th

### Notes

"***Failed to launch JVM***": A couple of users running on Windows 11 reported the same [issue 818](https://github.com/Audiveris/audiveris/issues/818).
Some users have encountered the error "***Failed to launch JVM***" and it is reported [here](https://github.com/Audiveris/audiveris/issues/818).

This is reportedly related to something called "Assistive Technology".
It is documented in this article [https://www.papercut.com/kb/Main/AssistiveTechnologynotfound](https://www.papercut.com/kb/Main/AssistiveTechnologynotfound)
Expand All @@ -137,16 +135,16 @@ The best fix for this problem is to disable the Access Bridge technology in the
To uninstall the program, open `Windows Settings`
(keyboard shortcut is `Windows + I`), and select the `Apps & features` section.

| Action | Illustration |
| :--- | :--- |
| In `Apps & features`, look for the Audiveris item and there press the `Uninstall` button | ![](../../assets/images/windows_uninstall.png) |
| Action | Illustration |
| :--- | :--- |
| In `Apps & features`, look for the Audiveris item and then press the `Uninstall` button | ![](../../assets/images/windows_uninstall.png) |

## Linux installer
## Linux

### Installation

Remark: A double-click on the `.deb` installer file would result in the opening of the `App Center`
which would choke on audiveris being potentially unsafe, etc.
which would report on Audiveris as being potentially unsafe, etc.

Instead, in a terminal, use a command like:
```sh
Expand All @@ -156,14 +154,14 @@ $ sudo apt install /path/to/Audiveris-<version>-ubuntu<osversion>-x86_64.deb
This installs the application in the target folder:
> /opt/audiveris/

This `/opt/audiveris` folder is organized as follows:
Which is organized as follows:
<pre>
/opt/audiveris
├── bin
│   └── Audiveris
├── lib
│   └── ...
└── share
/opt/audiveris
├── bin
│   └── Audiveris
├── lib
│   └── ...
└── share
└── ...
</pre>

Expand Down Expand Up @@ -191,14 +189,14 @@ $ sudo apt purge audiveris

The Audiveris installer for Linux uses the Flatpak utility and is hosted on the standard Flathub repository.

On the [Flathub site](https://flathub.org/), you can enter "audiveris" in the search field.
On the [Flathub site](https://flathub.org/), you can enter "audiveris" in the search field.
Or you can go directly to the [https://flathub.org/apps/org.audiveris.audiveris](https://flathub.org/apps/org.audiveris.audiveris) page.

For a manual install, you can use:
```sh
$ flatpak install flathub org.audiveris.audiveris
```
### Running
### Running

To launch the application, run the command:
```sh
Expand All @@ -217,7 +215,7 @@ This section explains how to install and run the Audiveris application on macOS
### Installation

1. **Obtain the proper DMG File for your architecture**
- Download or receive the proper `.dmg` file, that is either `Audiveris-<version>-macosx-arm64.dmg` or `Audiveris-<version>-macosx-x86_64.dmg`, from the source (e.g., a contributor or repository release).
- Download the proper `.dmg` file, that is either `Audiveris-<version>-macosx-arm64.dmg` or `Audiveris-<version>-macosx-x86_64.dmg`, from the source (e.g., a contributor or repository release).

2. **Open the DMG**
- Double-click the chosen `.dmg` file. This mounts the installer as a virtual disk on your desktop or in Finder.
Expand All @@ -228,9 +226,9 @@ This section explains how to install and run the Audiveris application on macOS

### Running

Since the app is not signed, macOS will block it by default. Follow these steps to allow it to run:
Since the app is not signed, macOS will block it by default. To allow it to run, follow these steps:

1. **Attempt to Open the App**
1. **Launch the App**
- Go to your **Applications** folder and double-click `Audiveris.app`.
- You’ll likely see a warning: *"“Audiveris” cannot be opened because it is from an unidentified developer."*

Expand All @@ -240,15 +238,15 @@ Since the app is not signed, macOS will block it by default. Follow these steps
- At the bottom, you’ll see a message: *“Audiveris” was blocked from use because it is not from an identified developer.*
- Click **"Open Anyway"** to allow the app to run.

3. **Launch the App**
3. **Launch the App Again**
- Double-click `Audiveris.app` again. You may see one final prompt asking for confirmation—click **"Open"**.
- The app should now launch successfully.

### Notes

- **Unsigned App**: The lack of a signature is due to the installer not being created with an Apple Developer account. This is a one-time adjustment; once approved, macOS will remember your choice.
- **Troubleshooting**: If the app still won’t open, ensure you’ve completed the privacy settings step. For persistent issues, contact the provider or check the Audiveris documentation.
- **Troubleshooting**: If the app still won’t open, ensure you’ve completed the adjust privacy settings step. For persistent issues, contact the provider or check the Audiveris documentation.

### Uninstallation

TODO
TODO
36 changes: 18 additions & 18 deletions docs/_pages/tutorials/install/sources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
---
layout: default
title: Building from sources
title: Building from source
nav_order: 3
parent: Installation
---
# Building from sources (Windows, macOS, Linux, ArchLinux)
# Building from source (Windows, macOS, Linux)
{: .no_toc }

{: .note }
> For GitHub users:
> - Audiveris "***master***" branch is updated only when a new release is published.
> - The Audiveris "***master***" branch is updated only when a new release is published.
> - Instead, Audiveris development happens continuously in the "***development***" branch,
> so pull and checkout this *development* branch to get and build the latest version.
> - See workflow details in the dedicated [Wiki article][workflow].
Expand All @@ -28,18 +28,18 @@ Table of contents
* [Gradle][gradle]: build tool.

* [Java Development Kit (JDK)][jdk]: version {{ site.master_java_version }}
(higher numbers may work, to be confirmed).
(higher numbers may work, to be confirmed).
This is the minimum Java version needed for the *master* branch.
The *development* branch may require a higher version, please
check on the Audiveris [project site](https://github.com/Audiveris/audiveris/tree/development?tab=readme-ov-file#development-versions).
The *development* branch may require a higher version; please
check on the Audiveris [project site](https://github.com/Audiveris/audiveris/tree/development?tab=readme-ov-file#development-versions).
Audiveris {{ site.audiveris_version }} runs only on 64-bit architectures.

* [FreeType library][freetype]: Unix-like platforms (including macOS) need FreeType in our $PATH
to handle those specific PDFs that contain vector graphics.
to handle those specific PDFs that contain vector graphics.
Fortunately, every known Unix-like OS distribution already contains a package for FreeType.

* Tesseract OCR: The Tesseract *libraries* are automatically pulled as Gradle dependencies,
but we will need some Tesseract *language files* for this OCR to work properly.
but we will need some Tesseract *language files* for this OCR to work properly.
Please check the [OCR languages](../../guides/main/languages.md) section.

## Clone, build and run
Expand All @@ -49,7 +49,7 @@ To clone the Audiveris project, we can use the following command in a directory
git clone https://github.com/Audiveris/audiveris.git
```

This will create a sub-directory named "audiveris" in our current directory and populate it with
This will create a sub-directory named "audiveris" in the current directory and populate it with
project material (notably source code and build procedure).

Now we move to this "audiveris" project directory:
Expand All @@ -58,8 +58,8 @@ Now we move to this "audiveris" project directory:
cd audiveris
```

Once in this `audiveris` project directory, we can select the branch we want.
By default, we are on `master` branch.
Once in the `audiveris` project directory, we can select which branch we want.
By default, we are on the `master` branch.
To use the `development` branch with its latest features, we can use:

```sh
Expand All @@ -68,7 +68,7 @@ git checkout development
# And to make sure we grab even the latest updates:
git pull --all
```
We can build the software via the command:
We can build the software with the command:
```sh
# (Linux & Mac, or Cygwin terminal under Windows)
./gradlew build
Expand All @@ -78,7 +78,7 @@ We can build the software via the command:
gradlew.bat build
```

We can run the software, with its graphical interface, via the command:
We can then run the software, and its graphical interface, with the command:

```sh
# (Linux & Mac, or Cygwin terminal under Windows)
Expand All @@ -95,13 +95,13 @@ behind the scenes, takes care of getting and launching the proper gradle version
## Alternative run

The gradle-based run, as described above, makes sure that all our potential modifications are
compiled before the application is launched.
compiled *before* the application is launched.
This is the preferred approach for a developer.

However, if we don't modify the code and merely want to launch the
application we don't need to go through gradle for each and every run.
However, if we don't modify the code and merely want to launch the
application, then we don't need to go through gradle for each and every run.

Because, once we have built the software with the gradle `build` command as stated above,
Once we have built the software with the gradle `build` command as stated above,
we now have a `app/build/distributions` subfolder in the project root with tarred/zipped libraries:

```sh
Expand All @@ -111,7 +111,7 @@ app/build/distributions/
└── app-5.5.0.zip
```

We can simply extract either one of these archives into a folder of our choice:
We can simply extract either of these archives into a folder of our choice:

```sh
# Either extract the .tar archive
Expand Down