INSTALL for Seq66 v. 0.99.26 and above
Chris Ahlstrom
2015-09-10 to 2026-07-06

If you are in a hurry, there are the quick steps to install Seq66,
given that all the DEPENDENCIES described later are in place:

    $ git clone https://github.com/ahlstromcj/seq66.git
    $ cd seq66
    $ ./work.sh
    $ sudo ./work.sh --install
    $ ./work.sh --clean
    $ ./build/cc/Seq66qt5/qseq66 &

Introduction:

    -   As of version 0.99.25, Seq66 is built on Linux using Meson instead
        of GNU Autotools. The Qt *.pro files for the qmake build can still
        be used.  Also, though files still have "qt5" in the name, currently
        Qt 6 is used by default, if available.
    -   Meson can also be used for the build on Windows. New scripting
        has been added to build the NSIS Seq66 Windows installer on
        Linux. Git Bash and MSYS2 can be used to build Seq66 in Windows.
        However, the qmake/batch-file build system is still in place.
    -   The Meson cross-file, for building the Windows version on Linux,
        does not yet work, except with the --no-gui option. We have
        not yet found a cross-build Qt installation without some
        show-stopper.
    -   Also see INSTALL.seq66.on.Ubuntu.md for Ubuntu Studio installs.

The "work.sh" script wraps around various combinations of settings,
meson setup calls, and compiling. See './work.sh --help'.

Getting Seq66 for Windows requires building the code or going to
"ahlstromcj/seq66" on GitHub to get an installation package or a
Windows release executable.

Different versions of the program can be built:

    -   qseq66.
        -   Has a Qt5/Qt6 user-interface a la Kepler34.
        -   "rtmidi" engine version: Native ALSA, JACK MIDI, and JACK
            transport; fall-back to ALSA;
    -   qpseq66.
        -   "portmidi" engine version: Linux and Windows. Built via
            qmake or meson, suitable for loading in QtCreator installed
            with mingw32 tools. 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.
        Can also build with "portmidi" instead of "rtmidi".

    Both qseq66 and seq66cli are built at the same time.

    We provide a Windows installer (an EXE) in the GitHub release area.
    It is possible to build the Windows version using Meson or
    QtCreator/qmake. See the batch script "nsis/build_release_package.bat";
    it builds using qmake and mingw. Meson can also be used to build
    the installer on Linux.

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

    -   Meson Build and Install; work.sh Install (Quick Install).
        Works on Linux and Window.
    -   Advanced Steps
        -   Pipe Option.
        -   Debugging.
    -   Qmake-based Install (Linux and Windows).
    -   Git Bash or MSYS2 Install (Windows only, very tricky to set up).

    One can also enable the Meson plug-in in Qt Creator and build Seq66.
    The build products are made in build/Desktop-Debug.

Linux Distro Package (seq66):

    Some Linux distros  (Arch Linux and KXStudio) may have put Seq66
    into a distro package. Here is a pointer to how one user installs it
    on a Raspberry Pi 3b+ running Raspian, from KXStudio repo using Muon:

        https://kde.org/applications/en/system/org.kde.muon

    For Arch Linux, see 'distros/arch/README'. Currently this is the
    pre-Meson version, 0.99.24.

Meson Build and Install:

    While Meson and Ninja commands can be used by the user to build,
    install, and uninstall Seq66, we provide a "work.sh" script
    similar to the old "bootstrap" script.  Here is the life cycle
    encapsulated.

        $ ./work.sh --clean
        $ ./work.sh                 [add the --debug option if desired   ]
        $ ./build/cc/Seq66qt5       [make sure it runs (the 'smoke' test)]
        $ sudo ./work.sh --install
          . . .
        $ sudo ./work.sh --uninstall

    The default build directory is './build/cc'. For the --clang option,
    it is './build/clang'. For --gnu or --gcc, it is './build/gcc'.
    For --debug, it is './build/debug'. For --windows (on Windows)
    it is './build/windows'.

    Note that our "lib66" GitHub project is used as a Meson "subproject";
    if installed on the system, that library is used.

    There are other options. Run the following to see them, and perhap examine
    the commands in the script:

        $ ./work.sh --help

Clang Compiler:

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

    Assuming that Clang is installed, simply run every time to build it:

        $ ./work.sh --clang

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.

Out-of-source Build:

    Meson automatically enforces an out-of-source build in a build
    directory. We define it as ./build/cc by default, but also as
    ./build/clang, ./build/gcc, etc. See the --help option of work.sh.

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

    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

Ubuntu Studio:

    See INSTALL.seq66.on.Ubuntu.md.

Git Bash or MSYS2 (tricky):

    Uses the work.sh script noted for Linux. It requires the installation
    of the toolchain, 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:

    See "./work.sh --help".

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

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

       ./pack --release rtmidi 0.99.25

    where rtmidi is the intended default build, and 0.99.25 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.

    TO DO: Can we revise for Meson by adding a --pipe option.

        $ CFLAGS="-pipe" ./work.sh [ TODO ]

    Then do the normal build.

Debugging:

    The default build (no ./work.sh options) is a release buld.
    We use cgdb instead of gdb for debugging.

        $ ./work.sh --debug

Qmake-based Install:

    This method is still supported. We use it with Qt Creator
    and as an extra option with Windows builds.

    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.

    Or the NSIS installer can be built on Linux after copying some
    Windows build files. See contrib/notes/nsis.text.

CONFIGURE OPTIONS FOR APPLICATION FEATURES:

    These options define or undefine various build macros:

    --nsm
    --no-nsm

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

    --no-jack
    
        Undefines the SEQ66_JACK_SUPPORT macro, which is otherwise defined
        by default.  This option disable all the other JACK options.
        Seq66, which incorporates a couple of JACK modules, but is useful in
        the Windows/OSX builds.

    --no-jack-transport

        Undefines the SEQ66_JACK_TRANSPORT macro.

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

    --portmidi

        We have gotten a few alternate implementations to work.  The normal
        build is effectively "rtmidi".  The --portmidi flag
        creates a qseq66 using ALSA on Linux via the local "PortMidi" library.

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_MISSING_JACK_VIRTUAL_PORTS (undefined)
        SEQ66_PORTMIDI_SYSEX_PROCESSING (undefined)
        SEQ66_PROVIDE_AUTO_COLOR_INVERSION  (experimental, investigative)
        SEQ66_SHOW_GM_PROGRAM_NAME (defined by default)
        SEQ66_USE_COLLAPSED_SLOT_POPUP_MENU
        SEQ66_USE_DEFAULT_PORT_MAPPING
        SEQ66_USE_METRONOME_FADE (undefined)
        SEQ66_USE_MIDI_MESSAGE_RINGBUFFER
        SEQ66_USE_SHOW_HIDE_BUTTON
        SEQ66_DRAW_PITCHBEND_AS_DOT (undefined)
        SEQ66_SHOW_GM_DRUM_NAME (undefined; leave undefined)

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:

        $ ./work.sh --clean
        $ ./work.sh --debug
        $ gdb ./build/cc/Seq66qt5/qseq66
        (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:

    -   Meson and ninja
    -   g++ or clang++
    -   Qt 5 or Qt 6. 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.

        For Ubuntu Studio 25 or thereabouts, see the document

            INSTALL.seq66.on.Ubuntu.md

   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:

        -   makensis

        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):

      To build the PDF user manual:

        $ ./work.sh --pdf

      The PDF is found in data/share/doc.

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

   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 or qsynth
        -   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
