From 3302a15f77bcc66b14afc13bafc405803dd70e12 Mon Sep 17 00:00:00 2001 From: Anton Latukha Date: Mon, 7 Oct 2019 09:35:57 +0300 Subject: [PATCH] BUILDING.md: clean-up & upd docs (#247) * BUILDING.md: rm tautology & move phrase to relevant place * BUILDING.md: mv place build info after dependency info & add subsection `autogen.sh` is in strange state, it consists only of `autoreconf --install`, and thanks for doing everything right. Also it spews `\n` verbatim, because person was writing/testing it on mac. Standartizing it in later proposal. * BUILDING.md: upd deps info to universal documentaion It is impossible to provide&keep the deps list/names for all OSes. Also different `configure` options require different dependencies provided. To provide the main documentation on why and what is needed is more important then a bunch of partial one-liner examples. & the differences between systems and package names are minimal. So better describe the required dependencies in terms of Debian/Ubuntu, and allow maintainers to fiqure-out their OS-specific variants. * BUILDING.md: Android: upd commands to be a commands block * BUILDING.md: mv Windows down, to logically group all *nix info * BUILDING.md: mv sec Additional info on deps to be after main info on deps * BUILDING.md: upd text properly outlining command & lib names * BUILDING.md: Deps: Jack: add mention of libqt5opengl5 Since it uses Qt, so also `libqt5opengl5`. * BUILDING.md: Additonal info: upd libglm Co-Authored-By: Mischa Spiegelmock * BUILDING.md: Building: upd ./configure comments Co-Authored-By: Mischa Spiegelmock --- BUILDING.md | 74 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 44 insertions(+), 30 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 9daeee09b1..9b02b866db 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,27 +1,40 @@ # Building projectM from source -When building on *nix and OSX, one uses the autogen/configure workflow. It is suggested to read configure.ac and the assorted Makefile.am files. +### Dependencies +Relevant for Linux distributions, FreeBSD, macOS: -``` -./autogen.sh # only needed if this is a git clone -./configure --enable-sdl -make -sudo make install -``` +* `autotools` `autoconf` +* `libtool`, or at least `pkg-config` +* `which` -### Linux (debian/ubuntu) dependencies -* `sudo apt install autoconf libtool libsdl2-dev libglm-dev qt5-default qtdeclarative5-dev libqt5opengl5-dev libjack-dev libpulse-dev libsdl-dev` +* `libglm-dev` -### FreeBSD dependencies -* `pkg install gcc autoconf automake libtool mesa-libs libGLU sdl2 glm` +Main build options & their requirements: -### Mac OS X dependencies -* `brew install glm sdl2 automake libtool pkg-config` +| Configure flag | Required dependency | Produced binary | +|-----------------|-------------------------------------------------------------------- |----------------------- | +| `--enable-sdl` | `libsdl2-dev` | `projectMSDL` | +| `--enable-qt` | `qt5-default` `qtdeclarative5-dev` `libpulse-dev` `libqt5opengl5` | `projectM-pulseaudio` | +| `--enable-jack` | `libjack2-dev`OR`libjack1-dev`; `qt5-default` `qtdeclarative5-dev` `libqt5opengl5`| `projectM-jack` | -### Building on Windows -Windows build bypasses the autogen/configure pipeline and uses the Visual Studio/MSVC files in `msvc/`. See `.appveyor.yml` for command line building. +#### Additional information on dependencies +* `libglm` (headers only) for matrix math is required. +* A modified version of `hlslparser` is included in Renderer and used to transpile HLSL shaders to GLSL +* OpenGL 3+ or OpenGLES is required +* `libsdl >= 2.0.5` is required for the SDL and emscripten apps. `src/projectM-sdl` is the current reference application implementation. maybe try getting that to build and run as your testbench. -Some dependencies are included verbatim (glew), while others leverage the NuGet ecosystem and are downloaded automatically (glm, sdl2). +If extra information needed - you can refere to `configure.ac` and the assorted `Makefile.am` files. + +### Building process under *nix systems +```sh +autoreconf --install # only needed if this is a git clone +# For macOS automation there is ./autogen.sh provided for autoreconf + +./configure --enable-sdl # supply additional options here, info in Dependencies + +make +sudo make install +``` ### OpenGL ES projectM supports OpenGL ES 3 for embedded systems. Be sure to configure with the `--enable--gles` flag. @@ -30,11 +43,19 @@ projectM supports OpenGL ES 3 for embedded systems. Be sure to configure with th * projectM is arch-independent, although there are some SSE2 enhancements for x86 * [Notes on running on raspberry pi](https://github.com/projectM-visualizer/projectm/issues/115) +### Building on Windows +Windows build bypasses the autogen/configure pipeline and uses the Visual Studio/MSVC files in `msvc/`. See `.appveyor.yml` for command line building. + +Some dependencies are included verbatim (glew), while others leverage the NuGet ecosystem and are downloaded automatically (glm, sdl2). + ### Build using NDK for Android Install Android Studio, launch SDK Manager and install NDK -`./autogen.sh` -`./configure-ndk` -`make && make install-strip` + +```sh +./autogen.sh +./configure-ndk +make && make install-strip +``` Now you should be able to copy ./src/libprojectM/.libs/libprojectM.so and appropriate headers to projectm-android, and build it using Android Studio @@ -42,25 +63,18 @@ and appropriate headers to projectm-android, and build it using Android Studio ## libprojectM -libprojectM is the core library. It is made up of three sub-libraries: +`libprojectM` is the core library. It is made up of three sub-libraries: #### Renderer -Made up of everything in src/libprojectM/Renderer. These files compose the libRenderer sub-library. +Made up of everything in `src/libprojectM/Renderer`. These files compose the `libRenderer` sub-library. #### MilkdropPresetFactory / NativePresetFactory -From their respective folders. Native presets are visualizations that are implemented in C++ instead of .milk preset files. They are completely optional. Milkdrop presets are technically optional but the whole thing is basically useless without them. +From their respective folders. Native presets are visualizations that are implemented in C++ instead of `.milk` preset files. They are completely optional. Milkdrop presets are technically optional but the whole thing is basically useless without them. If you don't want native presets, and you probably don't, don't bother with them. Ideally there should be a configure option to disable them, probably on by default (at this time this is needed for autoconf: https://github.com/projectM-visualizer/projectm/issues/99). -### Dependencies -* libglm for matrix math is required, just the headers though. We are considering "vendoring" them. -* A modified version of hlslparser is included in Renderer and used to transpile HLSL shaders to GLSL -* OpenGL 3+ or OpenGLES is required -* libsdl >= 2.0.5 is required for the SDL and emscripten apps. src/projectM-sdl is the current reference application implementation. maybe try getting that to build and run as your testbench. - - ### Assets -libprojectM can either have a configuration hard-coded or load from a configuration file. It's up to each application to decide how to load the config file. The config file can have paths defined specifying where to load fonts and presets from. +`libprojectM` can either have a configuration hard-coded or load from a configuration file. It's up to each application to decide how to load the config file. The config file can have paths defined specifying where to load fonts and presets from. You will want to install the config file and presets somewhere, and then define that path for the application you're trying to build.