Installation from source - arkq/bluez-alsa GitHub Wiki

@borine wrote: This revision contains package information obtained by browsing the repositories of various Linux distributions. Not all the dependencies listed have been tested for correctness or completeness. It would be most helpful if readers of this page could try out the build on their own preferred distribution and correct any errors or omissions here as appropriate.

This page shows step by step the installation process of BlueALSA from the source code for various Linux distributions.

BlueALSA uses the GNU autoconf/automake build system. Given BlueALSA's aim of small size and minimum redundancy, it makes many of its features optional and only includes them if explicitly requested when configuring the build. This guide lists all the available options and gives details of any extra dependencies introduced by each option.

For general help with using autoconf, see the GNU autoconf manual Running configure scripts. There are also many tutorials on the web, just search for gnu autotools tutorial. However, this guide aims to provide sufficient instructions so no prior special knowledge of GNU automake or autoconf is required to complete the task of BlueALSA build and installation.

This installation guide does not cover bluealsa daemon automatic startup; for systemd integration please look at the systemd wiki page.

Firstly make sure that all essential build tools are installed. These are:
git, autotools, libtool, pkg-config, gcc, binutils, and the standard unix shell utilities.

Also required are the third-party libraries on which BlueALSA depends. The essential ones required by the BlueALSA core functions are:
libasound, libbluetooth (5.51 or later), libglib2.0 (2.58.2 or later), libsbc (1.5 or later)

If building bluealsa-aplay (which is enabled by default) or bluealsa-cli then there is an additional dependency on:
libdbus (1.6 or later)

If building the optional man pages, there is an additional tool required, rst2man which is part of the python docutils project.

Here are some example install instructions for a few linux distributions; in each the first line installs the tools and the second installs the libraries:

sudo apt-get install git automake build-essential libtool pkg-config python3-docutils
sudo apt-get install libasound2-dev libbluetooth-dev libdbus-1-dev libglib2.0-dev libsbc-dev

sudo dnf install git automake libtool pkgconfig gcc python3-docutils
sudo dnf install alsa-lib-devel bluez-libs-devel dbus-glib-devel sbc-devel

sudo pacman -S git base-devel python-docutils
sudo pacman -S alsa-lib bluez-libs dbus glib2 sbc

Clone the BlueALSA source code from Github into your workarea:

git clone https://github.com/arkq/bluez-alsa.git
cd bluez-alsa

Prepare the auto configuration tools to use your development environment. It is very important to do this step after the essential requirements installation of step 1 above. In the bluez-alsa directory run the automatic reconfiguration as follows:

autoreconf --install --force

The --force option is necessary to ensure that the correct version identifier is compiled into the built executables. Re-run this command whenever the source code is updated, for example after using git pull.

Create a new directory in which to perform the build. This will keep the build products separate from the source code and make it easier to restart afresh if you need to change the configuration. We will call this directory "build", but you can use any unique name. If you are cross-compiling you may wish to create separate build directories, one for each host platform. You may also wish to have separate build directories for a debug build and a release build.

mkdir build
cd build

At this stage you need to decide which optional features you wish to include (if any). In order to compile additional codecs and utilities you must install additional dependencies. For more information on obtaining each individual dependency, see the section Additional Dependencies below. (Note that some codecs require a license, especially for commercial use).

The BlueALSA configure script offers all the standard autoconf options, and in addition the following specific options are available.

• --enable-debug  [since v1.0.0]
  enable debugging support (a lot of debug text will be written to the stderr of both the daemon and the alsa client).

• --enable-debug-time  [since v1.2.0]
  enable debug timing support

• --with-libunwind  [since v3.0.0]
  use libunwind for call-stack unwinding - requires libunwind 1.1 or later.

By default, the BlueALSA configure script builds only the mandated SBC codec support for the A2DP profile. To add support for other A2DP codecs, each must be explicitly enabled on the configure command line. The codecs that can be enabled are:

• --enable-aac  [since v1.2.0]
  enable AAC support - requires fdk-aac 0.1.1 or later development headers and libraries

• --enable-aptx  [since v1.3.0]
  enable aptX support - BlueALSA supports three alternative aptX libraries: openaptx by @arkq, libopenaptx by @pali, or libfreeaptx (which is a fork of libopenaptx and is used by Pipewire). Requires development headers and libraries from one of those three alternatives. By default this option selects openaptx (1.2.0 or later) by @arkq unless --with-libopenaptx or --with-libfreeaptx is used. Adding either --with-libopenaptx or --with-libfreeaptx option is recommended if one wants to use aptX codecs, as they have better decoder support.

• --enable-aptx-hd  [since v2.0.0]
  enable aptX HD support - requires openaptx development headers and libraries (unless --with-libopenaptx or --with-libfreeaptx is used; it is recommended to use one of those options for aptx HD).

• --with-libopenaptx  [since v3.1.0]
  use libopenaptx for aptX and aptX HD - requires libopenaptx 0.2.0 or later development headers and libraries.

• --with-libfreeaptx  [not yet released]
  use libfreeaptx for aptX and aptX HD - requires libfreeaptx 0.1.1 or later development headers and libraries.

• --enable-faststream  [since v4.0.0]
  enable FastStream support - no additional libraries required

• --enable-lc3plus  [since v4.0.0]
  enable LC3plus support - requires LC3plus development headers and libraries

• --enable-ldac  [since v2.0.0]
  enable LDAC support - requires ldacBT development headers and libraries (ldacBT-abr 1.0.0 or later, ldacBT-dec and ldacBT-enc 2.0.0 or later.

• --enable-mp3lame  [since v2.0.0]
  enable MP3 support - requires mp3lame development headers and libraries

• --enable-mpg123  [since v2.0.0]
  enable MPG123 decoding support - requires mpg123 1.0.0 or later development headers and libraries

By default, the BlueALSA configure script builds only the mandated CVSD codec for the HSP and HFP profiles. It is possible to also add support for the mSBC and LC3-SWB codecs for HFP by explicitly enabling them on the configure command line:

• --enable-lc3-swb  [not yet released]
  enable LC3-SWB support - requires liblc3 1.0.0 or later development headers and libraries

• --enable-msbc  [since v2.0.0]
  enable mSBC support - requires spandsp 0.0.6 or later development headers and libraries

BlueALSA can be built with additional features to improve compatibility with some other applications by enabling some or all of these features on the configure command line:

• --enable-ofono  [since v1.4.0]
  enable HFP over oFono - requires no extra libraries at build time. Including this option will enable BlueALSA's support for ofono. In this case BlueALSA will defer all telephone integration to oFono if an ofono service is discovered at run-time. If no ofono service is available then BlueALSA will fall back on its own internal HFP implementation.

• --enable-upower  [since v2.1.0]
  enable UPower integration - requires no extra libraries at build time. When built with this option, BlueALSA will advertise support for a battery level indicator to Bluetooth devices.

• --disable-payloadcheck  [since v1.3.0]
  disable RTP payload type check (workaround for a bug in PulseAudio versions before 13.0, and some Android versions) Earlier releases of PulseAudio, and also Android, set a non-compliant value in the payload type field of RTP packets, meaning that Bluetooth standard compliant devices and applications (such as BlueALSA) would reject those packets. This option disables that check in BlueALSA, permitting a computer running PulseAudio to use another computer running BlueALSA as an audio sink. This bug in PulseAudio was fixed in release 13.0; not sure which Android versions are affected.

A number of utility applications are included in the BlueALSA sources. These options determine whether they are built or not. See the linked manual page for more information about each utility.

• --disable-aplay  [since v1.2.0]
  disable building of the bluealsa-aplay tool. See manual page.
  bluealsa-aplay is built by default - this option removes it from the build.
  bluealsa-aplay requires libdbus 1.6 or later development headers and libraries.

• --enable-a2dpconf  [since v3.0.0]
  enable building of the a2dpconf tool. a2dpconf is a simple tool for decoding A2DP configuration blobs.

• --enable-cli  [since v3.1.0]
  enable building of the bluealsa-cli tool. See manual page.
  Requires libdbus (dbus-1 1.6 or later) development headers and libraries.

• --enable-rfcomm   [since v1.3.0]
  enable building of the bluealsa-rfcomm tool. See manual page.
  Requires readline development headers and libraries.

• --enable-hcitop  [since v1.3.0]
  enable building of hcitop tool. See manual page.
  Requires libbsd 0.8 or later and ncurses development headers and libraries.

• --enable-manpages  [since v3.0.0]
  build and install manual pages for the bluealsa daemon, the BlueALSA ALSA plugins, and the enabled utilities. Requires the utility rst2man from the docutils project.

• --enable-test  [since v1.4.0]
  build the unit test programs - requires check 0.9.10 or later testing framework. Some of the tests also require sndfile 1.0 or later; those tests will be omitted if sndfile is not available.

• --with-coverage  [since v3.0.0]
  use lcov for test coverage reporting - requires lcov 1.14 or later.

By default, BlueALSA will use the install prefix /usr. This is unusual for autoconf projects, which usually default to /usr/local. This choice was made because the alsa plugin modules must be installed in the same prefix as libasound, and most Linux distributions will have installed the alsa components in /usr.

From alsa release 1.1.7 or later, the main alsa runtime configuration file contains a hard-coded path to local configuration files: /etc/alsa/conf.d So, unless your distribution has patched that file, it is necessary to place the bluealsa local config file (20-bluealsa.conf) in that directory. The BlueALSA installer will by default do so. This can be overriden either with the standard option: --sysconfdir=DIR (to place the file in DIR/alsa/conf.d) or with the BlueALSA specific option: --with-alsaconfdir=DIR (to place the file in DIR)

For alsa release 1.1.6 and earlier, the bluealsa configure script will place the alsa configuration file in the default /usr/share/alsa/alsa.conf.d. This can be overridden with either the standard option --datadir=DIR (for DIR/alsa/alsa.conf.d) or with the bluealsa specific option: --with-alsaconfdir=DIR (to place the file in DIR).

From release 4.1.0 BlueALSA includes persistent storage for device volume settings. By default, configure will set the directory used for this storage to be /var/lib/bluealsa. However, if the --prefix=PREFIX option is given, then this default will be changed to PREFIX/var/lib/bluealsa. To select some other directory, use the --localstatedir=DIR standard option; in this case the BlueALSA storage directory will be DIR/lib/bluealsa. Note that when using systemd, the bluealsa executable will use the directory given by the systemd StateDirectory= directive relative to systemd's preset path for state files, resulting in /var/lib/bluealsa, overriding the compiled-in value set here by configure.

• --with-dbusconfdir=dir  [since v2.0.0]
  path to D-Bus system bus configuration files. By default, configure will use pkg-config to find the D-Bus configuration root on the build system, then append /dbus-1/system.d and install the D-Bus config file there (ignoring any --prefix setting). The current BlueALSA sources [not yet released] use pkg-config --variable=datadir dbus-1 (as now recommended by the D-Bus project), which typically evaluates to /usr/share/ giving a default path of /usr/share/dbus-1/system.d. BlueALSA releases 4.1.1 and earlier used pkg-config --variable=sysconfdir dbus-1 giving a typical default path of /etc/dbus-1/systemd.

If you are installing into a sysroot that is not the build system root, then you can use this option to override that default.

• --with-alsaplugindir=dir  [since v1.0.0]
  path where ALSA plugin files are stored. By default, configure will use pkg-config --variable=libdir alsa to find the ALSA library install root on the build system, then append /alsa-lib and install the ALSA plugin library files there (ignoring any --prefix setting). If you are installing into a sysroot that is not the build system root, then you can use this option to override that default.

• --with-alsaconfdir=dir  [since v1.4.0]
  path to ALSA add-on configuration files. By default configure will use the ALSA default location (relative to any --prefix= setting) for the build system. If you are installing into a sysroot that is not the build system root, then you can use this option to override that default.

• --with-bash-completion[=DIR]  [since v3.1.0]
  install a bash completion script in DIR (or in the bash completions default directory if DIR is not specified). This script requires the bash-completion 2.0 or later package to be installed on the runtime host.

• --enable-systemd  [since v4.0.0]
  install default systemd service unit files for bluealsa and bluealsa-aplay. Requires systemd version 200 or later.

• --with-systemdsystemunitdir=DIR  [since v4.0.0]
  directory in which to install systemd unit files. By default, configure will use pkg-config --variable=systemdsystemunitdir systemd to find the correct path. If you are installing into a sysroot that is not the build system root, then you can use this option to override that default.

• --with-systemdbluealsaargs=ARGS  [since v4.0.0]
  bluealsa arguments to be used in the installed bluealsa.service file, defaults to '-S -p a2dp-source -p a2dp-sink' if not specified

• --with-systemdbluealsaaplayargs=ARGS  [since v4.0.0]
  bluealsa-aplay arguments to be used in the installed bluealsa-aplay.service file, defaults to empty if not specified.

• --with-bluealsauser=USER  [since v4.1.0]
  set up the installation to run bluealsa as user USER, defaults to root if not specified. When used with bluez <= 5.50, USER must be a member of the "bluetooth" group. This option configures the bluealsa.service file and also configures D-Bus to permit USER to own the service name org.bluealsa. See D-Bus Policy for more information on the BlueALSA D-Bus policy file.

• --with-bluealsaaplayuser=USER  [since v4.1.0]
  configure the systemd bluealsa-aplay.service unit file to run bluealsa-aplay as user USER, defaults to root if not specified. USER must be a member of the "audio" group.

If necessary, it is possible to set various environment variables to alter choices made by the configure script - particularly fine-tuning the search paths for various components. To see a list of the variables that can be used, and a complete list of all command line options, in the build directory type:

../configure --help

In order to compile additional codecs and utilities, one must install additional dependencies as noted against the options above. These must be installed before running the configure script. Example package names for some distributions:

(*) - RaspberryPiOS repository does not have any built packages for fdk-aac so this must be built from source for this platform. Upstream sources are maintained on GitHub at https://github.com/mstorsjo/fdk-aac

(**) - ldacBT in distributions' repositories does not provide decoding support.

(***) - Some distributions' repositories include both libopenaptx and libfreeaptx, some have only one of them, some have neither. You should seek advice from your distribution for which to choose. If your distribution does not include either library, you can obtain the original sources from: pali/libopenaptx or libfreeptx.

Some dependencies are not available in the distributions' repositories, and must be built from source. See the respective project repository for instructions:

• openaptx
• ldacBT
• LC3plus - for more information and software download link see Fraunhofer IIS LC3/LC3plus and for build instructions see issue 479 (comment).

Once the required configuration options have been chosen, and the build dependencies installed, the build area can be configured. From within the build directory, type:
../configure --option1 --option2 ...

Some examples:

• To generate a simple debug build, with no additional options:
  ../configure --enable-debug

• To generate a debug build with support for AAC and compatible with older PulseAudio releases:
  ../configure --enable-debug --enable-aac --disable-payloadcheck

• To generate a release build with support for AAC, aptX, oFono and mSBC:
  ../configure --enable-aac --enable-aptx --with-libopenaptx --enable-ofono --enable-msbc

• To generate a release build with support for LDAC encoding and decoding (assuming that the full version of Sony libldac library was installed in the /opt/libldac directory):

  export LDAC_ABR_CFLAGS="-I/opt/libldac/include" LDAC_ABR_LIBS="-L/opt/libldac/lib -lldacBT_abr"
  export LDAC_DEC_CFLAGS="-I/opt/libldac/include" LDAC_DEC_LIBS="-L/opt/libldac/lib -lldacBT_dec"
  export LDAC_ENC_CFLAGS="-I/opt/libldac/include" LDAC_ENC_LIBS="-L/opt/libldac/lib -lldacBT_enc"
  ../configure --enable-ldac

In the build directory:

make
sudo make install

It is also necessary to install the runtime dependencies for all the libraries included in the build. For some distributions (such as Arch) both development and runtime components are included in a single package. For others (such as Debian and Fedora) separate packages must be installed. The following table gives the relevant package names for some distributions.

Debian based distributions require a particular version of runtime a library package to be specified. The best choice (and available choices) depends on the OS release in use. The table gives alternative packages for recent releases, however it may not always be kept up-to-date with the latest release.

(*) Not available in RaspberryPiOS repositories.

The alsa project team changed the default directory structure for config files with release 1.1.7. In order to ease the transition when upgrading to this release, some distributions (e.g. Debian buster) support both structures by placing config files in the old structure, and creating symlinks to the files from the new structure (or vice-versa). The BlueALSA make install does not create these sym links. Therefore, to make sure that all applications obtain the correct alsa configuration, it may be advisable to manually create the symlink for the BlueALSA config (20-bluealsa.conf) on such distributions.

The "old" directory for alsa config files before 1.1.7 was:

/usr/share/alsa/alsa.conf.d/

and the "new" directory in alsa 1.1.7 and later is:

/etc/alsa/conf.d/