1# Building and installation 2 3You are generally recommended to use your distro's package manager to install 4Notcurses; it is [available](https://repology.org/project/notcurses/versions) 5prepackaged on many distributions. If you wish to build from source, read on. 6 7## Prerequisites for building 8 9Acquire the current source via 10 11`git clone https://github.com/dankamongmen/notcurses.git` 12 13There are no submodules. Dependencies are fairly minimal. 14 15### APT 16 17Install build dependencies: 18 19`apt-get install build-essential cmake doctest-dev libavformat-dev libavutil-dev libdeflate-dev libgpm-dev libncurses-dev libqrcodegen-dev libswscale-dev libunistring-dev pandoc pkg-config` 20 21If you only intend to build core Notcurses (without multimedia support), you 22can omit `libavformat-dev`, `libavutil-dev`, and `libswscale-dev` from this 23list. `zlib1g-dev` can be substituted for `libdeflate-dev`; build with 24`-DUSE_DEFLATE=off` in this case. If you don't want to generate QR codes, you can 25omit 'libqrcodegen-dev'. 26 27If you want to build the Python wrappers, you'll also need: 28 29`apt-get install python3-cffi python3-dev python3-pypandoc python3-setuptools` 30 31### RPM 32 33Install build dependencies: 34 35`dnf install cmake doctest-devel libdeflate-devel ncurses-devel gpm-devel libqrcodegen-devel libunistring-devel OpenImageIO-devel pandoc` 36 37If you only intend to build core Notcurses (without multimedia support), you 38can omit `OpenImageIO-devel`. If you're building outside Fedora Core (e.g. with 39RPM Fusion), you might want to use FFmpeg rather than OpenImageIO. If you don't 40want to generate QR codes, you can omit 'libqrcodegen-devel'. `zlib-devel` can 41substitute for `libdeflate-devel`; build with `-DUSE_DEFLATE=off` in this case. 42 43### FreeBSD / DragonFly BSD 44 45Install build dependencies: 46 47`pkg install archivers/libdeflate devel/ncurses multimedia/ffmpeg graphics/qr-code-generator devel/libunistring` 48 49If you only intend to build core Notcurses (without multimedia support), you 50can omit `multimedia/ffmpeg`. If you do not want to deflate Kitty graphics, 51you can omit 'archivers/libdeflate'; build with `-DUSE_DEFLATE=off` in this 52case. If you don't want to generate QR codes, you can omit 53'graphics/qr-code-generator'. 54 55### Microsoft Windows 56 57Building on Windows requires [MSYS2](https://www.msys2.org/) in its 5864-bit Universal C Runtime (UCRT) incarnation. This builds native Windows DLLs 59and EXEs, though it does not use Visual Studio. Install build dependencies: 60 61`pacman -S mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-libdeflate mingw-w64-ucrt-x86_64-libunistring mingw-w64-ucrt-x86_64-ncurses mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-openimageio mingw-w64-ucrt-x86_64-toolchain` 62 63Note that on Windows, OpenImageIO is (at the moment) recommended over FFmpeg. 64 65If you only intend to build core Notcurses (without multimedia support), you 66can omit `mingw-w64-ucrt-x86_64-openimageio`. If you do not want to deflate Kitty 67graphics, you can omit 'mingw-w64-ucrt-x86_64-libdeflate'; build with 68`-DUSE_DEFLATE=off` in this case. 69 70You'll want to add `-DUSE_DOCTEST=off -DUSE_PANDOC=off` to your `cmake` invocation. 71`notcurses-tester` does not currently work on Windows, and you probably don't want 72to build the UNIX-style documentation. 73 74## Building 75 76* Create a subdirectory, traditionally `build` (this is not strictly necessary, 77 but it keeps your source tree clean). Enter the directory. 78* `cmake ..` 79 * You might want to set e.g. `CMAKE_BUILD_TYPE`. Use `-DVAR=val`. 80 * To build without multimedia support, use `-DUSE_MULTIMEDIA=none`. 81* `make` 82* `make test` 83* `make install` 84* `sudo ldconfig` 85 86The default multimedia engine is FFmpeg. You can select a different engine 87using `USE_MULTIMEDIA`. Valid values are `ffmpeg`, `oiio` (for OpenImageIO), 88or `none`. Without a multimedia engine, Notcurses will be unable to decode 89images and videos. 90 91To get mouse events in the Linux console, you'll need the GPM daemon running, 92and you'll need run `cmake` with `-DUSE_GPM=on`. 93 94Run unit tests with `make test` following a successful build. If you have unit 95test failures, *please* file a bug including the output of 96 97`./notcurses-tester -p ../data` 98 99(`make test` also runs `notcurses-tester`, but hides important output). 100 101To watch the bitchin' demo, run `make demo` (or `./notcurses-demo -p ../data`). 102More details can be found on the `notcurses-demo(1)` man page. 103 104Install with `make install` following a successful build. This installs the C 105core library, the C headers, the C++ library, and the C++ headers (note that 106the C headers are C++-safe). It does not install the Python wrappers. To 107install the Python wrappers (after installing the core library), run: 108 109``` 110cd cffi 111python setup.py build 112python setup.py install 113``` 114 115The Python wrappers are also available from [PyPi](https://pypi.org/project/notcurses/). 116 117### Build options 118 119To set the C compiler, export `CC`. To set the C++ compiler, export `CXX`. The 120`CMAKE_BUILD_TYPE` CMake variable can be defined to any of its standard values, 121but must be `Debug` for use of `USE_COVERAGE`. 122 123* `DFSG_BUILD=off`: leave out all content considered non-free under the Debian Free 124 Software Guidelines 125* `BUILD_TESTING=on`: build test targets 126* `USE_ASAN=off`: build with AddressSanitizer 127* `USE_CXX=on`: build C++ code (requires a C++ compiler) 128* `USE_COVERAGE=off`: build coverage support (for developers, requires use of Clang) 129* `USE_DOCTEST=on`: build `notcurses-tester` with Doctest, requires `BUILD_TESTING` 130 * `USE_DOCTEST=on` requires `USE_CXX=on` 131* `USE_DOXYGEN=off`: build interlinked HTML documentation with Doxygen 132* `USE_GPM=off`: build GPM console mouse support via libgpm 133* `USE_MULTIMEDIA=ffmpeg`: `ffmpeg` for FFmpeg, `oiio` for OpenImageIO, `none` for none 134 * `oiio` cannot be used with `USE_CXX=off` 135* `USE_PANDOC=on`: build man pages with pandoc 136* `USE_POC=on`: build small, uninstalled proof-of-concept binaries 137* `USE_QRCODEGEN=off`: build qrcode support via libqrcodegen 138* `USE_STATIC=on`: build static libraries (in addition to shared ones) 139