Help

Building Benben

These instructions will explain how to build Benben from source. These are always for the latest stable version.

Requirements

Benben has been developed with Crystal >= v1.5.x and <= v1.12.x in mind. Other versions will likely work, but may require a bit of tweaking and are not officially supported.

Regardless of your Crystal version, you will need an updated version of the Shards command that has Fossil support built into it. Support was introduced in Shards 0.17.1. If you have problems, you can always use my personal fork of Shards as a temporary measure.

Fossil is required as some of Benben's dependencies are in Fossil repositories.

You will need some specific C libraries installed as well:

  • S-Lang (2.3.2 or higher)
  • libmpg123 (1.29 or higher)
  • libopus
  • libvorbis
  • libxmp (4.6.0 or higher recommended)
  • libsidplayfp (2.1.0 or higher recommended)
  • libwavpack (5.0 or higher recommended)
  • One or more (preferably all) of the following:
    • PulseAudio
    • PortAudio
    • libao

You will also need Ruby, but just for building Benben.

Note: only Linux is officially supported at the moment. Other platforms may build successfully (it's tested on Dragonfly BSD semi-regularly), but you may need to change some of the source files in either Benben, some build flags, or its dependencies.

Tips for Building On a BSD System

The ZStandard bindings require some Bash scripts to run in order to be built, and thus Bash needs to be installed. These scripts are also written to expect Bash to be located at /bin/bash, so you will either need to ensure Bash is there (or symlinked there), or modify lib/zstd/build/*.sh accordingly.

Benben has been successfully built and used on Dragonfly BSD v6.4 using Crystal v1.5.1. To do this you will want to disable PulseAudio support and adjust the CFLAGS at build time. Do this by invoking the build process as such:

$ CFLAGS="-I/usr/local/include" rake benben[speed,pulseaudio]

Other BSD systems may also work but are not tested.

Getting the sources

$ fossil clone https://chiselapp.com/user/MistressRemilia/repository/benben/
$ cd benben

Following this, you should check out the version of your choosing. For example, for v0.6.0:

$ fossil checkout v0.6.0

You can also check out the trunk code, though these instructions may require some tweaking from here on.

Configuring Benben

Regardless of how you end up building Benben, before you do, you will need to run the configure.rb script that comes with the sources. This will generate a config.cr file that will store system-wide configuration. Run ./configure.rb --help to see the customization settings.

Building with Rake

Using Rake is the easier way to build Benben. For a default build, you can just run rake from the root repository directory. The binary will be in the bin/ directory.

The default target is benben, and it has it two options. The first option can be one of four values:

  • super-debug: Produce a debug build + lots of extra output.
  • debug: Produces an un-optimized binary with full debug information.
  • normal: Produces an optimized binary.
  • o3: Produces an optimized binary that may be slightly faster than a normal build.
  • speed: The default. Produce a fully optimized binary with the -D*_wd40 flags and with debug information stripped.

The second option can be used to disable certain audio drivers. At least one audio driver must be enabled. The default will include all supported audio drivers. Multiple drivers can be separated with a colon.

  • portaudio: Disabled PortAudio support.
  • pulseaudio: Disabled PulseAudio support.
  • libao: Disabled libao support.

Examples of setting these:

  • rake benben[speed]: Build the most optimized binary (and strip it).
  • rake benben[debug]: Build an un-optimized debug build.
  • rake benben: Exact same as running just rake or rake benben[speed].
  • rake benben[speed,portaudio]: Build the most optimized binary (and strip it), and disable PortAudio.

There are also a few other targets:

  • rake deps: Runs shards install or shards update.
  • rake clean: Removes the compiled binary from the bin/ directory.
  • rake clobber: The same as rake clean, except this also removes the lib/ directory and the shards.lock file.
  • rake man: Builds the man Page.
  • rake help: Show information about the targets.
  • rake lint: Run the Ameba linter.

Example Commands

# Build a release version of Benben.
$ rake

# Release build without PulseAudio support
$ rake benben[speed,pulseaudio]

# Debug build
$ rake benben[debug]

# List all of the targets
$ rake -T

Building manually with Shards

You can forego using Rake if you choose and just use Shards directly. When doing this, it's important to be aware of a few compiler flags:

  • -Dpreview_mt: This is REQUIRED for Benben.
  • -Dyunosynth_wd40: YunoSynth (the library providing VGM playback) will normally do a few extra checks at runtime for things like rendering buffer sizes. This is normally only needed during development, and are included mostly for easier debugging. Specifying -Dyunosynth_wd40 disables these checks, thereby saving a few extra CPU cycles (Crystal will still do bounds checks on the buffers at runtime).
  • -Dyunosynth_debug: Enables a lot of runtime debugging output.
  • -Dhaematite_wd40: Haematite (the library providing SoundFont synthesis) will normally do a few extra checks at runtime for things like rendering buffer sizes. This is normally only needed during development, and are included mostly for easier debugging. Specifying -Dhaematite_wd40 disables these checks, thereby saving a few extra CPU cycles (Crystal will still do bounds checks on the buffers at runtime).
  • -Dremiaudio_wd40: RemiAudio (the library responsible for WAV/Au output and DSP effects) will normally do a few extra checks at runtime for things like rendering buffer sizes. This is normally only needed during development, and are included mostly for easier debugging. Specifying -Dremiaudio_wd40 disables these checks, thereby saving a few extra CPU cycles (Crystal will still do bounds checks on the buffers at runtime).
  • -Dbenben_debug: Enables extra debugging output from Benben itself.
  • -Dbenben_no_pulse_audio: Disables PulseAudio support. You may also want -Dremisound_no_pulseaudio to disable it in the RemiSound library.
  • -Dbenben_no_port_audio: Disables PortAudio support. You may also want -Dremisound_no_portaudio to disable it in the RemiSound library.
  • -Dbenben_no_ao: Disables libao support. You may also want -Dremisound_no_libao to disable it in the RemiSound library.
  • -Dremilib_no_assertions: Disables all assertions on the Crystal side of things. Not recommended.

Additionally, the Rakefile normally sets both -Dstrict_multi_assign and -Dno_number_autocast. You may want to do the same.

Examples:

$ shards build --release --no-debug -p -Dpreview_mt -Dyunosynth_wd40

$ shards build -p -Dpreview_mt -Dbenben_no_pulse_audio -Dremisound_no_pulseaudio

$ shards build -p -Dpreview_mt -Dyunosynth_debug