Skip to content

Latest commit

 

History

History
153 lines (111 loc) · 4.95 KB

INSTALL.md

File metadata and controls

153 lines (111 loc) · 4.95 KB
Raw

Installing beep

This document describes how to install beep from sources and how to set up the system afterwards.

If you are using beep as shipped in a binary distribution package, that package should have done most of those steps for you. The one notable exception should be the step adding users to the beep group.

If this file leaves open an installation question, please file an issue at https://github.com/spkr-beep/beep/issues so we can see whether we can improve the documentation or the installation procedure on the beep side.

Build requirements

  • GNU make
  • clang or gcc
  • Linux kernel headers

Compile and Install

The basic way to build and install beep is

[user@host beep]$ make
[user@host beep]$ make install-nobuild

beep does not have a configure script, so to make some configuration options last over different make invocations, do generate a local.mk file containing the appropriate definitions:

  • The buildsystem will use whatever value CC is as a compiler, and use a few tools like PANDOC for building html from markdown. You can set these to your desired values, including PANDOC=false to disable building and installing html files.

  • The installation location will be written into some files during make, and will then be used during make install. The default installation location is prefix=/usr/local, with bindir, docdir, htmldir, mandir, etc. being used for more specialized installation directories. For installing into a chroot environment, the install target(s) support DESTDIR=/path/to/chroot.

  • For changing compilation and linking, define CPPFLAGS, CFLAGS, LDADD, and LDFLAGS.

You can override any of these variables from the make command line like e.g.

[user@host beep]$ make prefix=$HOME/.local
[user@host beep]$ make prefix=$HOME/.local install

or you can put that definition (and others) into a local.mk file:

[user@host beep]$ cat>local.mk<<EOF
prefix = $HOME/.local
EOF
[user@host beep]$ make
[user@host beep]$ make install

If you need to run make install as another user to have the required permission to install file to special locations, we recommend the special make install-nobuild target: make install-nobuild will categorically NOT run any build processes as the priviledged user who is running make install-nobuild.

If you run make install immediately after make all, there should be no build processes necessary, but if you have changed any of the source files after the make all, files will be rebuilt.

So a system wide install into /usr/local would be best achieved with

[user@host beep]$ make
[user@host beep]$ sudo make install-nobuild

For the complete list of those variables, see the top of GNUmakefile.

Some more compilation related variables mostly useful for distribution packagers are documented in PACKAGING.md.

System configuration

  • The Linux kernel driver pcspkr must be loaded to provide access to the PC speaker via the evdev and console APIs.

  • To have the system load the pcspkr kernel module by default during each system boot, add a line

    alias platform:pcspkr pcspkr

    to a modprobe config file, like e.g. /etc/modprobe.d/pcspkr-beep.conf.

  • To load the pcspkr kernel module right now without needing to boot, run

    modprobe pcspkr

    To unload the pcspkr driver again, run

    modprobe -r pcspkr

  • Set up the udev rules which set the device special file permissions for non-root users according to PERMISSIONS.md.

    You can test whether the permission setup work by unloading and then loading the pcspkr kernel module, as loading the module will cause all the udev rules to run.

  • On some systems with integrated speakers like e.g. laptops from the IBM/Lenovo Thinkpad series, there is no separate physical speaker for the PC speaker.

    Instead, the square wave sound generated by the PC speaker goes to the integrated speakers through a mixer chip, where it is mixed with PCM sound, CD drive audio, line in, microphone in, and other sources.

    On these systems, you might need to configure the mixer to make the PC speaker audible through the laptop speakers, e.g.

    • Start alsamixer.
    • Find the correct card (switch with the F6 key).
    • Maybe enable loopback.
    • Unmute the appropriate PC speaker source (m key) and turn up its volume.
    • Weirdly, a microphone volume below 0% apparently can also silence the PC speaker beeps.

    Some experimentation might be required.

    Of course, these mixer settings must be saved before the next system reboot so that the reboot can restore the mixer settings. Some systems save the mixer settings as part of their shutdown procedure, others may need you to save them explicitly.