INSTALL for Seq66 v. 0.93.0
Chris Ahlstrom
2015-09-10 to 2021-03-28

Getting Seq66 requires building the code or going to the
"sequencer64-packages/seq66" project directory on GitHub.
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 GUI-less version of Seq66, which can run from the
        console or as a daemon, controlled via MIDI and playlists.
        Still being worked on.

    We provide a Windows installer in the "sequencer64-packages" project in
    GitHub, in the "seq66" subdirectory.  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)

Linux Distro Package (seq66):

    Your favorite Linux distro may have put seq66/sequencer64 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

Normal (automake) 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:

        $ ./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".  Then try
    the above commands again.

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.

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.  There are now 5 versions:

       2.   Seq64cli/seq66cli:           ./bootstrap -er -cli
       3.   Seq64qt5/qseq66:             ./bootstrap -er -qt

       (Currently, one can use "-cli" and "-rm" together to build both
       versions in one pass.  However, there are issues still to resolve,
       so do not do it!)
   
       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 [ -rm | -cli | -qt ]
       $ ./bootstrap -er [ -rm | -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 [ -rm | -cli | -qt ]
       $ ./bootstrap -ed [ -rm | -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

   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 Sequencer64 User Manual from:

            http://github.com/ahlstromcj/sequencer64-doc.git

       It contains a prebuilt PDF version of the manual, as well as the
       LaTeX 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

        or

    $ 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

    See the contrib/scripts/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.  However
        this support is still in progress and not yet complete.

    --enable-lash

        Defines the SEQ66_LASH_SUPPORT macro, which is undefined by default.
        Use this if you still use LASH session management.  However this
        support is still in progress for 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:

    The following items are not yet part of the configure script, but can
    be edited manually to achieve the desired settings.  Only crazy or
    experiment-happy people will normally want to change the define-state of
    these macros.  We have consolidated them into a single file,
    libseq66/include/seq66_features.h, to make them easier to find and edit.

    SEQ66_USER_CALLBACK_SUPPORT

        This option activates support for "rtmidi"-style user-callbacks.
        This support is used only in some test code (see the midi_probe)
        module, and is no long included in normal builds.

    SEQ66_USE_METRONOME_FADE

        Define if it is desired to waster CPU cycles on a fancier
        time-indicator bar.

    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:

        USE_STAZED_RANDOMIZE_SUPPORT
        USE_STAZED_SEQDATA_EXTENSIONS
        USE_STAZED_SELECTION_EXTENSIONS
        USE_STAZED_EVEN_ODD_SUPPORT

        Also, the GitHub project "Kepler34" has some features we want to adopt
        before we make our version of its conversion to the Qt library.

        SEQ66_SEQUENCE_EDIT_MODE

        See libseq66/src/midi/midifile.cpp for details.

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 -rm
        $ make &> make.log
        $ gdb ./Seq64rtmidi/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
      -  libjack-jackd2-dev
      -  liblash-compat-dev (optional, needed for LASH support)
      -  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)

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

      - 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
         -  qtbase5-dev-tools
         -  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.

         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.

   Runtime:

      -  libatk-adaptor (and its dependencies)
      -  libgail-common (and its dependencies)
      -  Some distros (Arch?) may need a gambas3-gb-qt5-opengl package to be
         installed.  Not sure what is up with that.

   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

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

         ./make_dox reference
         ./make_dox clean

      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
