- General information
- Downloading LV
- Building LV
- Example: Clang debug builds
- Forcing Reconfiguration
- Hacking LV
- Code formatting style (FIXME: Format and edit this)
- Documentation (FIXME: Format and edit this)
- Source Control (FIXME: Format and edit this)
- Bug Reporting (FIXME: Format and edit this)
- Coding in C++
Clone this wiki locally
Note: This is for development on master (0.5.0). 0.4.x uses GNU Autotools.
LV is hosted on GitHub at libvisual.github.com.
To obtain the latest development snapshot:
git clone https://github.com/Libvisual/libvisual.git
LV is written in a mix of C11 and C++20, and as such, requires an up-to-date C/C++ compiler to build. Compilers tested and known to work are GCC 11+ and Clang 14+.
Building Libvisual requires CMake 3.20 or above. The command to configure the build is:
For general development, we recommend building out-of-source. This keeps the source tree clean, and makes it possible to create multiple test builds with different options. To build LV out-of-source, enter a new directory and run.
Build options are configured with the -D argument e.g.:
cmake -D<NAME>=<VALUE> <...>
Below is a list of common options for developers. For a full list, run: cmake -L
CMAKE_INSTALL_PREFIX- Root installation directory. Defaults to /usr/local on Linux.
CMAKE_BUILD_TYPE- Build profile. Options:
CMAKE_C_COMPILER- C compiler path
CMAKE_CXX_COMPILER- C++ compiler path
ENABLE_DOCS- Enable documentation. Options:
ENABLE_FATAL_WARNINGS- Turn all compiler warnings to errors. Options:
ENABLE_PROFILING- Build with profiling information (for
ENABLE_DOCS- Generate API documentation using Doxygen. Options:
ENABLE_TESTS- Build and run unit tests. Options:
Example: Clang debug builds
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ <...>
CMake stores its build configuration in a cache (CMakeCache.txt) to avoid re-running expensive tests on each build run. To force a complete reconfiguration, you can delete the cache file:
rm -f CMakeCache.txt
Once configuration is complete, run Make to begin the compiling:
To see every command run during a build, including compiler flags:
To use all of your CPU threads, specify the thread count using
After compilation is finished, install the built library with:
Code formatting style (FIXME: Format and edit this)
LV Core follows a single style. No tabs, or trailing whitespaces
Ditto for build scripts
Plugin scaffolding, the part that interfaces with LV, are written in the same style. Some use tabs for indentation, but this is just a holdover from older LV releases which used tab indentation.
Plugin implementation are written in various styles, as they're largely retained from the original code we imported. We're not mass reformatting or reindenting to avoid making the commit history hard to trace (the blame view will become less useful).
The golden rule is to follow the style of whatever's already written, depending on the source file.
Documentation (FIXME: Format and edit this)
We use Doxygen. First configure the build with -DENABLE_DOCS=yes. Run
make docsafterwards to generate the documentation. The files will be in docs/.
Please follow the general style described in the official Javadoc style guide
Source Control (FIXME: Format and edit this)
We obviously use git. The GitHub repository is the master repository.
All development currently happens in master, so please base your development there. Once we release 0.5.0, we will create a separate devel branch and work there. Then on, HEAD will be considred the latest stable. New features must be written in separate branches, branched off devel. Once a feature branch is proven relatively stable, we will integrate it into devel. Once devel proves stable and ready for release, we will merge it into master. For more information on this workflow, see this page.
Good Git guide: Pro Git (http://git-scm.com/book)
Bug Reporting (FIXME: Format and edit this)
Track bugs in the GitHub issue queue.
Please include a basic description of the issue, and how to reproduce it. The issue queue is also used to file enhancement requests and general development goals. For these, include a description and some rationale.
Coding in C++
- We have largely replaced C with C++ in LV Core.
- If you're relatively new to modern C++, please familiarise yourself with:
- Scope based resource management, or more commonly known as RAII in C++ literature (Resource Acquisition Is Initialization).
- Vocabulary types:
- Standard library containers:
std::array- fixed size array
std::vector- dynamically sized array
std::unordered_map- unsorted associative container (e.g. hash table)
std::map- sorted associative container (e.g. dictionary)
- Range-based for loops for iterating through container elements.
- Smart pointers i.e.
std::shared_ptr. Note that LV uses a version of
boost::intrusive_ptr) that works on objects with an embedded reference count for performance reasons.
- Lambdas and their various variable capture modes i.e. by reference, by value.
- Pimpl idiom for hiding private class details
- If you're a bit more advanced:
- Rvalue references and object moving (as opposed to copying)
- Compile-time evaluations via
- Generic programming with templates: type traits, CRTP, concepts (template argument constraints).
- Recommended Readings
- A Tour of C++ by Bjarne Stroustrup (2nd Edition or later)
- Effective Modern C++ by Scott Meyers
- Modern C++ Cheatsheet
- C++ Core Guidelines
- Recommended Viewing