= Setup and Installation

include::common.adoc[]

== Requirements

Here are the basic requirements and dependencies that you need to satisfy in order to use the library:

. A C++20 compiler
. git
. https://cmake.org/[CMake] 3.16.0 or higher

Additionally, the following libraries are automatically fetched using CMake's FetchContent:

1. The https://github.com/cycfi/infra/[Cycfi infra library]
2. http://www.portaudio.com/[portaudio] Audio I/O library.
3. http://portmedia.sourceforge.net/portmidi/[portmidi] MIDI I/O library.

=== C++20

The Q library currently supports macOS, Windows, and Linux. On macOS, we support both https://developer.apple.com/xcode/[XCode]. The Q library is tested with XCode 10 and XCode 11. On Windows, we support Windows 10 with https://visualstudio.microsoft.com/vs/[Visual Studio 2022]. On Linux, we support both https://clang.llvm.org/[Clang] and https://gcc.gnu.org/[gcc]. Get the latest version with a C++20 compiler. The https://www.jetbrains.com/clion/[CLion] IDE is supported on all platforms.

The Q library currently supports the following platforms and tools:

* MacOS
    ** https://developer.apple.com/xcode/[XCode] (Tested with XCode 10 and XCode 11)
* Windows
    ** Windows 10 with https://visualstudio.microsoft.com/vs/[Visual Studio 2022]
* Linux
    ** https://clang.llvm.org/[Clang] (Clang 11.0.0 or later)
    ** https://gcc.gnu.org/[gcc] (GCC 11 or later)
* All platforms
    ** https://www.jetbrains.com/clion/[CLion] IDE

NOTE: Additionally, the core of the Q library (q_lib), excluding the audio IO layer (q_io), is compatible with any platform that has a fully conforming C++20 compiler. This core subset has been successfully tested on various embedded platforms, including the Teensy and STM32 series.

=== Git

Clone the Q DSP library and its submodules:

----
git clone --recurse-submodules https://github.com/cycfi/Q.git
----

=== CMake

Make sure you have https://cmake.org[CMake] 3.16.0 or higher.
Follow the installation procedure for your platform.

=== Generating the Project using CMake

There are multiple ways to generate a project file using CMake depending on your platform and desired IDE, but here are some examples for MacOS 10.14, Windows 10 and, and Ubuntu 16.04:

== MacOS

Using https://developer.apple.com/xcode/[XCode]:

. CD to the Q library: `cd Q`
. Make a build directory: 'mkdir build'
. CD to the the Q/build directory: `cd build`
. Invoke cmake: `cmake -G"Xcode" ../`

If successful, cmake will generate an XCode project in the build directory.

== Windows

Using https://visualstudio.microsoft.com/vs/[Visual Studio 2022]

. CD to the Q library: `cd Q`
. Make a build directory: 'mkdir build'
. CD to the the Q/build directory: `cd build`
. Invoke cmake: `cmake -G"Visual Studio 17 2022" ../`

If successful, cmake will generate an Visual Studio solution project in the build directory.

== Linux

Using https://wiki.debian.org/DebianPackageManagement[dpkg packaging system],
stock g++ compiler and http://www.codeblocks.org/[CodeBlocks].

. CD to the Q library: `cd Q`
. Make a build directory: 'mkdir build'
. CD to the the Q/build directory: `cd build`
. Invoke cmake: `cmake -G"CodeBlocks - Unix Makefiles" ../`

If successful, cmake will generate a CodeBlocks project in the build
directory.

== Build and Test

Build the project generated by cmake.

Try running the tests and examples. If you intend to run the executables directly from the command line, make sure to change the directory to the same level where the `audio_files` is (e.g. 1 folder up on XCode builds). Some tests and examples may require audio clips that are found in this folder.

To make sure everything is OK, try running the `sin_osc.cpp` example. Make sure your system's default audio device is set up and ready to play audio. The `sin_osc.cpp` program should play a 5 second 440 Hz sine wave. You might also want to try running the `list_devices.cpp` example that prints out all detected audio and MIDI devices.

'''

_Copyright (c) 2014-2024 Joel de Guzman. All rights reserved._
_Distributed under the https://opensource.org/licenses/MIT[MIT License]_
