Skip to content

Installation from source

Jump to bottom Edit New page
borine edited this page Jun 25, 2022 · 68 revisions

@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 bluez-alsa from the source code for various Linux distributions. This installation manual does not cover bluealsa daemon automatic startup, because it is out of the scope of the bluez-alsa repository. E.g. for systemd integration please look at the systemd integration wiki page.

1. Install Required Tools and Essential Development Libraries

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, libglib2.0, libsbc

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

If building the optional man pages, there is an additional tool required, rst2man.

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:

Debian/Raspberry Pi OS/Ubuntu

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

Fedora

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

Arch

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

2. Obtain The Latest Source Code and Prepare For Build

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 essential requirements installation. 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.

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

3. Configure The Build Directory

At this stage you need to decide which optional features you wish to include (if any). In order to compile additional codecs and utils, one must install additional dependencies, which are noted 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 options are available:

Debugging options

  • --enable-debug
    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
    enable debug timing support

  • --with-libunwind
    use libunwind for call-stack unwinding - requires libunwind 1.1 or later.

A2DP options

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 with release 3.0.0 are:

  • --enable-aac
    enable AAC support - requires fdk-aac development headers and libraries

  • --enable-aptx
    enable apt-X support - BlueALSA supports two alternative aptX libraries: openaptx by @Arkq or libopenaptx by @pali. Requires development headers and libraries from one of those two alternatives. By default this option selects openaptx by @Arkq unless --with-libopenaptx is used.

  • --enable-aptx-hd
    enable apt-X HD support - requires openaptx development headers and libraries (unless --with-libopenaptx is used)

  • --with-libopenaptx
    use libopenaptx for apt-X (HD); adding this option is recommended if one wants to use apt-X codecs - requires libopenaptx development headers and libraries

  • --enable-faststream
    enable FastStream support - no additional libraries required

  • --enable-ldac
    enable LDAC support - requires ldacBT development headers and libraries

  • --enable-mp3lame
    enable MP3 support - requires mp3lame development headers and libraries

  • --enable-mpg123
    enable MPG123 decoding support - requires mpg123 development headers and libraries

HSP/HFP options

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

  • --enable-msbc
    enable mSBC support - requires spandsp development headers and libraries

Compatibility options

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
    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
    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
    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.

Utility options

A number of utility applications are included in the bluealsa sources. These options determine whether they are built or not.

  • --disable-aplay
    disable building of bluealsa-aplay tool
    bluealsa-aplay is built by default - this option removes it from the build.

  • --enable-a2dpconf
    enable building of a2dpconf tool.

  • --enable-cli
    enable building of bluealsa-cli tool.

  • --enable-rfcomm
    enable building of bluealsa-rfcomm tool - requires readline development headers and libraries.

  • --enable-hcitop
    enable building of hcitop tool - requires libbsd and ncurses development headers and libraries.

Documentation options

  • --enable-manpages
    build and install manpages for bluealsa, bluealsa-aplay, bluealsa-cli, and bluealsa-rfcomm (if not disabled).

Testing options

  • --enable-test
    build the unit test programs - requires check testing framework.

  • --with-coverage
    use lcov for test coverage reporting - requires lcov 1.14 or later.

Installation options

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 on 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).

  • --with-dbusconfdir=dir
    path to D-Bus system bus configuration files. By default, configure will use pkg-config --variable=sysconfdir dbus-1 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). 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
    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
    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]
    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 package to be installed on the runtime host.

  • --enable-systemd
    install default systemd service unit files for bluealsa and bluealsa-aplay.

  • --with-systemdsystemunitdir=DIR path to systemd unit files.

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

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

Environment Settings

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

Additional Dependencies

In order to compile additional codecs and utils, 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:

Dependency Debian / Raspberry Pi OS / Ubuntu Fedora Arch
check check check check
fdk-aac libfdk-aac-dev (*) fdk-aac-devel libfdk-aac
lcov lcov lcov lcov
ldacBT (**) libldacbt-enc-dev
libldacbt-abr-dev
libbsd libbsd-dev libbsd-devel libbsd
libopenaptx (***) libopenaptx-dev libopenaptx-devel libopenaptx
libunwind libunwind-dev libunwind-devel libunwind
mpg123 libmpg123-dev mpg123-devel mpg123
mp3lame libmp3lame-dev lame-devel lame
ncurses libncurses-dev ncurses-devel ncurses
readline libreadline-dev readline-devel readline
spandsp libspandsp-dev spandsp-devel spandsp

(*) - 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 is available since Debian 11 (bullseye) and does not provide decoding support.

(***) - libopenaptx has only recently been added to many distributions' repositories. If your distribution does not include this library, you can obtain the original sources from pali/libopenaptx

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

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

4. Finally, Compile and Install:

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.

Dependency Debian / Raspberry Pi OS / Ubuntu Fedora
bash-completion bash-completion bash-completion
dbus dbus dbus-glib
fdk-aac libfdk-aac1 (*)
libfdk-aac2 (*)		 fdk-aac
libasound libasound2 alsa-lib
libbluetooth libbluetooth3 bluez-libs
libbsd libbsd0 libbsd
libglib2.0 libglib2.0-0 dbus-glib
libopenaptx libopenaptx0 libopenaptx
libsbc libsbc1 sbc
libunwind libunwind8 libunwind
mpg123 libmpg123-0 mpg123
mp3lame libmp3lame0 lame
ncurses libncurses5
libncurses6		 ncurses
readline libreadline7
libreadline8		 readline
spandsp libspandsp2 libspandsp

(*) 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/

Add a custom footer
Add a custom sidebar
Clone this wiki locally