Skip to content

Hacking guide

Jump to bottom
Chong Kai Xiong edited this page Feb 17, 2023 · 19 revisions
Clone this wiki locally

Note: This is for development on master (0.5.0). 0.4.x uses GNU Autotools.

General information

Website: http://libvisual.org

Downloading LV

LV is hosted on GitHub at libvisual.github.com.

To obtain the latest development snapshot:

git clone https://github.com/Libvisual/libvisual.git

Building LV

Requirements

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

Configuration

Building Libvisual requires CMake 3.20 or above. The command to configure the build is:

cmake .

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.

cmake <PATH-TO-SOURCE-TREE>

Options

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: Release, Debug (case-sensitive)
  • CMAKE_C_COMPILER - C compiler path
  • CMAKE_CXX_COMPILER - C++ compiler path
  • ENABLE_DOCS - Enable documentation. Options: yes, no.
  • ENABLE_FATAL_WARNINGS - Turn all compiler warnings to errors. Options: yes, no.
  • ENABLE_PROFILING - Build with profiling information (for gprof). Options: yes, no.
  • ENABLE_DOCS - Generate API documentation using Doxygen. Options: yes, no.
  • ENABLE_TESTS - Build and run unit tests. Options: yes, no.

Example: Clang debug builds

cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ <...>

Forcing Reconfiguration

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

Building

Once configuration is complete, run Make to begin the compiling:

make

To see every command run during a build, including compiler flags:

make VERBOSE=1

To use all of your CPU threads, specify the thread count using -j:

make -j$(nproc)

Installing

After compilation is finished, install the built library with:

make install

Hacking LV

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 docs afterwards 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: std::tuple, std::optional, std::variant, std::any
    • 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::unique_ptr and std::shared_ptr. Note that LV uses a version of std::shared_ptr called IntrusivePtr (based on 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.
    • auto declarations
    • 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 constexpr and consteval
    • Generic programming with templates: type traits, CRTP, concepts (template argument constraints).
  • Recommended Readings
  • Recommended Viewing