INSTALL

INSTALL for Seq66 v. 0.99.18 and above
Chris Ahlstrom
2015-09-10 to 2025-01-20

Getting Seq66 requires building the code or going to "ahlstromcj/seq66" on
GitHub to get an installation package or a Windows release executable.
The bootstrap setup is primarily aimed at developers, but is easy to use
with the instructions below.  Different versions of the program can be built:

    -   qseq66.  The "rtmidi" engine version, with a Qt5 user-interface a la
        Kepler34.  Native ALSA, JACK MIDI and JACK transport; fall-back to
        ALSA; support for Meta events (Set Tempo and Time Signature).  The
        official version of Seq66, Linux only.
    -   qpseq66. The same as qseq66, except that the internal "portmidi"
        implementation is used as the MIDI engine.  Linux and Windows.  Built
        via qmake and suitable for loading in QtCreator installed with mingw32
        tools. To build it in Windows, specify the Mingw library and tools
        when installing QtCreator.  See "Qmake-based Install" below.
    -   seq66cli.  A headless version of Seq66, which can run from the
        console or as a daemon, controlled via MIDI and playlists.
    -   seq66clip. The seq66cli app with "portmidi" instead of "rtmidi".

    We provide a Windows installer (an EXE) in the GitHub release area.  It is
    also fairly easy to build the Windows version using QtCreator/qmake.  See
    the DOS batch script "nsis/build_release_package.bat"; it not only builds
    it using qmake and mingw, but also describes how to create Windows
    packages.

Below are sections for various ways of installing this project by building
from source code:

    -   Linux Distro Package
    -   Normal (automake) Install
    -   Bootstrap Install (Quick Install)
    -   Advanced Steps
        -   Pipe Option:
        -   Debugging:
    -   Qmake-based Install (Linux and Windows)
    -   MSYS2 Install (Windows only, and NOT YET READY)

Linux Distro Package (seq66):

    Your favorite Linux distro may have put seq66 into a distro package.  For
    example, Arch Linux and KXStudio have packages.  Here is a pointer to how
    one user installs it on a Raspberry Pi 3b+ running Raspian:

        Installed it from from KXStudio repo using Muon:
        https://kde.org/applications/en/system/org.kde.muon

Autotools Build and Install:

    The normal install is meant for for those who do not want to install a lot
    of extra developer packages, and want to use the standard "configure"
    steps.  These steps build the most common version of Seq66, "qseq66" with
    the internal "rtmidi" engine.  The "configure" script for the build
    process means one needs to install the various "dev" dependencies.  The
    conventional way to install applications from source code is to use the
    source tarball and run the normal mantra:

        $ contrib/scripts/reconf        # if needed (see below)
        $ ./configure
        $ make
        $ sudo make install

    If "configure" or "make" emit errors, make sure libtool is installed, and
    then run the script "reconf", stored in "contrib/scripts/reconf".  This
    should make soft links to /usr/share/automake files in the aux-files
    directory. Then try the above commands again.

    Another variation is to change the client/port name from the default,
    which is "seq66". Add an option like the following:

        $ ./configure --with-client=myseqclient

    This change will show up in the MIDI I/O tabs in Edit / Preferences.

    Also note that the qmake executable must exist.  If it is not found,
    check for the existence of an alternate name (e.g. qmake-qt5) and
    make a soft link to it.

Bootstrap Install:

    The quick install is meant for for those who do not want to install a lot
    of extra developer packages, and want to use the standard "./configure ;
    make ; make install" mantra.  These steps build the default version of
    Seq66, "qseq66" with the internal "rtmidi" engine.  The "configure" script
    for the build process means one needs to install the various "dev"
    dependencies.  See the DEPENDENCIES section.  The build commands
    require automake and libtool to be installed.  Grab a Seq66 tarball
    and untar it.  Go to the "seq66" directory and run these commands:

        $ ./bootstrap -er
        $ make &> make.log
        $ sudo make install

    Study the "bootstrap" script to understand how it uses autoheader,
    automake, libtool, and other standard Linux build tools.  This build
    results in the "qseq66" executable.

Clang Compiler:

    Even if one has the GNU compilers installed, one can still install Clang
    and use it for the build.

    Assuming the configure script is up-to-date, and either the base clang or
    a specific version (e.g. clang-16) is installed, then the configure
    command can be used for the base clang, or the bootstrap script for a
    specific version:

        $ CC=clang CXX=clang++ ./configure
        $ make &> make.log
        $ sudo make install

    One might need to make symbolic links to the desired versions of these
    compiler, for example clang-16 and clang++-16.

    The alternative is to make sure the setup is fully cleaned, and use
    a bootstrap option:

        $ ./bootstrap --full-clean
        $ ./bootstrap --clang [... other options]

FreeBSD:

    While FreeBSD can build Seq66, there are some issues that need to be
    addressed. See contrib/notes/freebsd.text for complete information.
    The recommended method of building Seq66 is discussed there. Basically,
    after making sure all dependencies are installed, run the qbuild.sh script
    and set up for usage of JACK. This advice is volatile.

    See the discussion in contrib/notes/freebsd.text.

Qt and Command-Line Merged Build:

    Per package-manager request, one can build and install both qseq66 and
    seq66cli in one pass. Either of the following setups should work.

        $ ./bootstrap --both

    or

        $ ./bootstrap
        $ ./configure --enable-both

Out-of-source Build:

    Here is an example, assuming one just downloaded the latest code:

        $ ./bootstrap --full-clean
        $ ./bootstrap
        $ mkdir build
        $ cd build
        $ ../configure --enable-both (or other options)
        $ make -j 4 &> make.log      (check it for errors/warnings)
        $ sudo make install          (in this example, both qseq66 & seq66cli)

OpenSUSE:

    Directions from the Seq66 GitHub sivecj/seq66 fork. First, install these
    packages:

    $ sudo zypper in libjack-devel liblo-devel alsa-devel libqt5-qtbase-devel \
        libqt5-linguist-devel

    Next, link the binary files from Qt5 without the "-qt5" at the end. Link them
    to your ~/.local/ directory and add the directory to the PATH only if
    required:

    $ mkdir -p ~/.local/bin/qt
    $ ln -s /bin/qmake-qt5 ~/.local/bin/qmake
    $ ln -s /bin/rcc-qt5 ~/.local/bin/rcc
    $ ln -s /bin/uic-qt5 ~/.local/bin/uic
    $ ln -s /bin/lrelease-qt5 ~/.local/bin/lrelease
    $ ln -s /bin/lupdate-qt5 ~/.local/bin/lupdate
    $ ln -s /bin/moc-qt5 ~/.local/bin/moc
    $ export PATH=$PATH:~/.local/bin/qt

    One might need to run the "reconf" script located in contrib/scripts/reconf.
    Otherwise ./configure drops an error.  Lastly, run ./configure and make.

    Also see contrib/scripts/make-qt5-links for OpenSUSE and Fedora, which
    encapsulates the commands shown above.

Fedora:

    Similar to OpenSUSE above.

    $ sudo dnf install qt5-qtbase qt5-qtbase-devel qt5-linguist \
            jack-audio-connection-kit-devel liblo-devel alsa-lib-devel

MSYS2:

    Uses the bootstrap script noted for Linux. It requires the installation
    of the toolchain, libtool, qt5-base, all prefixed by either
    "mingw-w64-x86_64-" (preferred) or "mingw-w64-i686-".  See
    contrib/notes/msys2-packages.text for the complete list.
    
    Also, edit the .bashrc file to add the following line:

        export PATH=/mingw64/bin:$PATH

    Close the terminal window and open a new one to set the PATH.

Advanced Steps:

    These steps are meant for those who want to try the various versions of
    Seq66, and do not mind installing a lot of extra developer software.

   0.  Preload any DEPENDENCIES, as listed at the end of this document.
       However, if some are missing, the configure script will tell you,
       or, at worst, a build error will tell you.

   1.  Check-out the branch you want, if you do not want "master".  Make a
       branch if you want to make changes.  The active branches are "master",
       "playlist", and "qt5_reconcile".  The comand "git branch -a" will
       show other branches not yet deleted.  See GitHub.

   2.  The first thing to do is decide what version of Seq66 you want to
       build:

       1. Seq66qt5/qseq66:      ./bootstrap -er
       2. Seq66cli/seq66cli:    ./bootstrap -er -cli
       3. Seq66cli/seq66clip:   ./bootstrap -er -cli -pm
       4. qpseq66 Linux:        Qmake/qbuild.sh/Qtcreator in shadow directory
       5. qpseq66 Windows:      Qmake/Qtcreator/build_release_package.bat

       For the first two: from the top project directory, run one of the
       commands above (they auto-configure) or run the following commands,
       which set up a release build of seq66 (native JACK, native ALSA
       fallback).

       $ ./bootstrap            (only if the configure script does not exist)
       $ ./configure [options]

       If you do not want to see a lot of output, the stock autotools
       option "--enable-silent-rules" can be added to the ./configure command.
       Otherwise:

       $ ./bootstrap --enable-release [ -cli | -qt ]
       $ ./bootstrap -er [ -cli | -qt ]

       Note that the options in brackets are optional.  The default is
       equivalent to "-rm -qt".

       For debugging without libtool getting in the way, just run the
       following command, which will add the --enable-debug and
       --disable-shared options to a configure run:

       $ ./bootstrap --enable-debug [ -cli | -qt ]
       $ ./bootstrap -ed [ -cli | -qt ]

       There are also configure options as described below, and conditional
       macros in the header files.  The configure options can be supplied to
       the ./configure command, while build macros can be defined (in the
       code) to even further tailor the build.

       To learn more, run

       $ ./bootstrap --help

       If there are build issues, try again after running:

       $ ./bootstrap --full-clean

   3.  Run the make command:

       $ make &> make.log

       This procedure no longer builds the documentation. If you do care about
       programmer documentation, change to the doc/dox directory and run
       "./make_dox reference" and "./make_dox notes".

       WARNING:  "./make_dox reference" is currently BROKEN, even though
                 no errors/warnings are shown in the Doxygen log files.
      
       You can add options to "make", such as "V=0" (enable silent build),
       "V=1" (enable the normal verbose build), and "-j n" (use n processors
       to speed up the build).

   4.  To install, become root and run:

       # make install

       Note that we have removed the developer reference manual from the
       automated build (see the Doxygen DEPENDENCIES below), but the existing
       documents will still be installed.

   5.  See the additional features that can be enabled, below, using 
       build macros.

   6.  Also grab the Seq66 User Manual from the "doc" directory.
       It contains a prebuilt PDF version of the manual, as well as the
       LaTeX and make files needed to rebuild it.

   7.  If you want to generate your own source/configure tarball for
       distributing Seq66, use the pack script:

       ./pack --release rtmidi 0.94.6

       where rtmidi is the intended default build, and 0.94.6 is the version
       of the project.  The branch is included in the resulting tarball name;
       the usual branch would be "master".

Pipe Option:

    The gcc -pipe option uses pipes, rather than temporary files, for
    communication between the various stages of compilation. This fails to work
    on some systems where the assembler is unable to read from a pipe; the
    GNU assembler can do it.

        $ CFLAGS="-pipe" ./bootstrap -ed
        $ CFLAGS="-pipe" ./configure --enable-debug --disable-shared

    Then do the normal make.

Debugging:

    Normally, one can bootstrap or configure with the --enable-debug option.
    However, on some machines (e.g. Debian Sid running gcc 9), the debug build
    fails because it cannot find one of the library symbols.  In that case,
    one can either use a qmake debug build or the following sequence of
    commands:

        $ ./bootstrap --full-clean
        $ ./bootstrap
        $ ./configure --enable-debug    [note the lack of "--disable-shared"]
        $ make &> make.log              [verify that there are no errors]
        $ libtool --mode=execute gdb ./Seq66qt5/qseq66

    We use cgdb instead of gdb for debugging.

Qmake-based Install:

    A build based on QtCreator and Qmake is available, to build the project on
    Windows, though we created this build on Linux first to work out the
    numerous "gotchas" with QtCreator, QMake, and the internal Seq66
    "architecture".
    
    The Qmake-based build is designed to use the local PortMidi library (by
    default), which is necessary for running Seq66 on Windows or Mac OSX.  It
    can be configured to build using the local RtMidi library by adding
    "rtmidi" to the CONFIG variable (see below).  The Qmake build also uses
    the Kepler34-based Qt 5 user interface.  This user interface is currently
    similar to the Gtkmm 2.4 user interface, but supports a different (better)
    feature set, and uses the Seq66 libraries internally.

    The first way to use this build is to run QtCreator and load the
    seq66.pro file.  This method can be used if you do not care for the
    command-line.  However, if the installer for QtCreator did not
    set up the default "kit" properly, create a good kit manually.
    If the kit is set up properly, the "seq66.pro" entry in the left
    project panel will show the other "pro" files as subprojects.  Note that
    a successful build will put the generated files in a "shadow" directory
    parallel with the "seq66" directory, such as:
    
        build-seq66-Desktop_Qt_5_10_1_MinGW_32bit-Debug
    
    Do not forget to "Configure Project" before trying to build it!

    The second way to use this build is to just use qmake to do a "shadow
    build".  Assuming you are in the "seq66" directory:

        $ cd ..
        $ mkdir shadow-debug-build
        $ cd shadow-debug-build
        $ qmake -makefile -recursive "CONFIG += debug" ../seq66/seq66.pro
        $ make &> make.log
        $ gdb ./Seq66qt/qpseq66 (for debugging)

    One can also use "CONFIG += release", or just leave that off entirely.
    We get a nice build that works under Linux or Windows.  Currently, we have
    tried only using the "mingw" tools in Windows, not the "msvc" (Microsoft)
    tools.  For debugging, QtCreator can be used.

    To create an installer package for Windows, see the instructions at the
    top of the "nsis/Seq66Setup.nsi" file. One can build the Seq66
    application in Windows, and then build the installer for it in Windows or
    Linux (makensis).

    The Qmake setup uses "PortMidi" by default, but an "RtMidi" version can be
    built as well:

        $ qmake -makefile -recursive "CONFIG += rtmidi" ../seq66/seq66.pro
        $ qmake -makefile -recursive "CONFIG += debug rtmidi" ../seq66/seq66.pro

    Followed by the "make" operation. See the "contrib/scripts/qbuild.sh"
    shell script (which replaces the qbuild Bash script) for an automation
    of this process.

Windows:

    To build a Windows NSIS installation package, the DOS batch script
    "nsis/build_release_package.bat" can be used.  See the top of that file for
    the procedure to follow.

CONFIGURE OPTIONS FOR APPLICATION FEATURES:

    These options define or undefine various build macros:

    --enable-rtmidi

        Defines SEQ66_RTMIDI_SUPPORT to enable our heavily modified "rtmidi"
        library.  This option enables the usage of native JACK MIDI which will
        fall back to ALSA if JACK is not running.  Builds Seq66rtmidi/seq66.

    --enable-nsm
    --disable-nsm

        Controls the SEQ66_NSM_SUPPORT macro, which is defined by default.
        This will allow the Non Session Manager to control Seq66.

    --disable-jack
    
        Undefines the SEQ66_JACK_SUPPORT macro, which is otherwise defined
        by default.  This option is not viable for the "rtmidi" version of
        Seq66, which incorporates a couple of JACK modules, but is useful in
        the Windows/OSX builds.

    --enable-jack-session

        Defines the SEQ66_JACK_SESSION macro, which is defined if JACK session
        support is defined, and the jack/session.h file is found.  Because
        JACK has deprecated its session management, and now recommends the Non
        Session Manager (NSM), this option is now disabled by default.  Cannot
        be enabled in the Windows/OSX builds.

    --enable-portmidi
    --enable-rtmidi

        We have gotten a few alternate implementations to work.  The normal
        build is effectively --enable-rtmidi.  The --enable-portmidi flag
        creates a new application, seq66portmidi, that is based on using ALSA
        on Linux via the local "PortMidi" library.

        SEQ66_PORTMIDI_SUPPORT
        SEQ66_RTMIDI_SUPPORT

MANUALLY-DEFINED MACROS IN CODE:

    Read the descriptions of the various macros defined in
    libseq66/include/seq66_features.h, and decide if you want to define
    or undefine them, before building the application.  Only crazy or
    experiment-happy people will normally want to change the define-state of
    these macros. In addition, sprinkled throughout the code are macros
    like the following:

    USE_xxxxxx:
    SEQ66_xxxxxx_TMI:

        This category of macros are usually undefined values that let us keep
        old or experimental code around in case we decide it was the better
        code after all.  Generally, you do not want to change the status of
        these macros unless you are very familiar with the code and willing to
        temporarily break stuff or add annoying console output.  The "TMI" in
        some denotes debug code that dumps too much information (TMI) to the
        console, so has to be enabled by editing it on those occasions where
        you really want it.

        We have incorporated some very useful code from the Seq32 project
        of the user "stazed".  He includes some new features and some bug
        fixes that we had overlooked.  At present, we are not enabling this
        functionality, just adding it, macroed out by the following macros:

        SEQ66_PROVIDE_AUTO_COLOR_INVERSION  (experimental, investigative)
        SEQ66_USE_SHOW_HIDE_BUTTON
        SEQ66_USE_DEFAULT_PORT_MAPPING
        SEQ66_USE_MIDI_MESSAGE_RINGBUFFER
        SEQ66_PORTMIDI_SYSEX_PROCESSING (undefined)
        SEQ66_USE_METRONOME_FADE (undefined)
        SEQ66_MISSING_JACK_VIRTUAL_PORTS (undefined)
        SEQ66_PROVIDE_AUTO_COLOR_INVERSION

REPORTING ISSUES:

   Should one be unfortunate enough to experience a segmentation fault
   (i.e. the infamous "crash"), here is the most complete way to diagnose the
   error, if we cannot replicate it:

        $ ./bootstrap --full-clean
        $ ./bootstrap -ed
        $ make &> make.log
        $ gdb ./Seq66qt5/seq66
        (gdb) r    [add your command-line arguments here if needed]
                   [replicate the crash]
        (gdb) bt   [does a backtrace]

    Then highlight, copy, and paste the stack trace and attach it to the bug
    report.  Might have to Page Up to see the relevant parts of the stack
    trace.

DEPENDENCIES:

   With luck, the following dependencies will bring in their own dependencies
   when installed.

   Code:

    -   libasound2-dev (alsa-devel on OpenSUSE)
    -   libjack-jackd2-dev
    -   liblo-dev (needed for NSM/OSC support, but not optional)
    -   libpng-dev (replaces libpng12-dev with libpng16, latest Debian Sid,
        and brings in libpng-tools)
    -   libpthread (normally already included in a Linux distro)

        Also see the sections on OpenSUSE and Fedora below.

    Qt Builds:

      This lists comes from the m4 file, and has been abbreviated.  Some of
      these are surely not needed and we can eliminate them from the test at
      some point. Left off are the initial "libQt" or "libqt" and final
      "5-dev" items in the library names. The obviously necessary ones (*)
      come first; they are specified in m4/ax_have_qt_min.m4, which provides
      the AX_HAVE_QT_MIN test used in the configure.ac script. The rest of
      them seem to be brought in as sub-dependencies, so make sure they are
      all installed if your attempt to build qseq66 fails.  See "Build tools"
      below.

    -   Core *
    -   Gui *
    -   Widgets  *
    -   Xml
    -   OpenGL 
    -   PrintSupport 
    -   QuickTest 
    -   Concurrent 
    -   DBus 
    -   Qml 
    -   Network 
    -   Test 
    -   Sql

   Build tools:

    -   automake and autoconf
    -   autoconf-archive
    -   g++
    -   make
    -   libtool
    -   Qt 5.  Install qtcreator only if you want it, as it installs 650 Mb
        worth of files.  One can just install the bare minimum:

        -   qt5-default (Important!)
        -   qtbase5-dev (might be installed after installedin qt5-default)
        -   qtbase5-dev-tools (ditto)
        -   qtdeclarative-dev-tools or qtdeclarative5-dev-tools
            (qtdeclarative5-dev?)
        -   qtchooser
        -   qt5-qmake
        -   qtdesigner; optional if you want to tweak the GUIs, not huge,
            provided by the qtttools5-dev-tools package in Debian.
        -   qtcreator; also optional, but handy.  Unmark/uninstall the
            "clang" packages that are recommended unless you want clang.

        To setup Qt, first run the command "qtchooser -l".  If more than one
        version of Qt is installed, their numbers are all listed.  Make sure
        that "5" is in the list, and then add this line to your .bashrc file:

            export QT_SELECT=5

        This allows builds in bash to use the correct version of Qt.
        Also, for appearances on non-KDE systems, consider:

        -   Installing the qt5ct package (Debian/Ubuntu)
        -   Adding "export QT_QPA_PLATFORMTHEME=qt5ct" to .bashrc.

   Raspberry Pi:

        A few notes while trying to get Seq66 built on a Raspberry Pi 3 Model
        B+.  The Raspian on this board, installed via NOOB, could ultimately
        not load some Qt dependences.  Ended up installing OpenSUSE, and
        installed Qt Creator to save time.

   Windows Installer:

        One can build the Windows installer under Linux (see the "nsis"
        sub-directory).  To build it on Windows, install the NSIS 3
        program, available at

            https://sourceforge.net/projects/nsis/files/NSIS%203/3.08/nsis-3.08-setup.exe/download

        Be sure to add the location of makensis.exe to the Windows PATH.

   Runtime:

        -   libatk-adaptor (and its dependencies)
        -   libgail-common (and its dependencies)
        -   jack_control (optional; jack-example-tools on Arch Linux)

   Documentation (now optional, must be built manually):

      We have removed the automatic generation of the developer reference
      documentation.  It is a pain to deal with relative to the number of
      times one needs to read it.  To build it, change to the doc/dox
      directory and run "./make_dox reference".  There is now a shorter,
      more useful "Developer Notes" document that can be built using
      "./make_dox notes".  Be aware that the PDF files will always be present
      and installed, even if not necessarily up-to-date with the latest code.

        -   Source-code documentation:
            -   doxygen and doxygen-latex
            -   graphviz
            -   texlive
        -   User manual (additional packages):
            -   latexmk
            -   pdf2latex

      To build the PDF user manual, change to the doc/latex directory and
      run "make".  The PDF is found in data/share/doc.

      To build the Doxygen documentation manually, change to the doc/dox
      directory and run:

         ./make_dox reference
         ./make_dox clean

      Currently, we do not care if this works.  Too much information.

      To install the documentation to /usr/local/doc/seq66-0.90:

         ./make_dox install
      
   Debian packaging:

      See the README file in the Debian directory.

        -   debhelper
        -   dh-autoreconf (Perl)
        -   fakeroot

   MingW:

      Avoid use of AC_CYGWIN and AC_MINGW32.  Specify the mingw compiler when
      installing qmake/qtcreator for Qmake/Qt5 builds on Windows.

   Other:

        -   git
        -   vim or emacs

   Testing (optional):

        -   qjackctl
        -   hydrogen
        -   klick (a command-line metronome)
        -   qtractor or other MIDI sequencers
        -   gmidimonitor or (better) midisnoop
        -   sendmidi
        -   python-dbus (for contrib/scripts/startjack usage)
        -   a2jmidid (exposes Seq24 ALSA MIDI ports to JACK)

# vim: sw=4 ts=4 wm=4 et ft=sh