5.1 KiB

Raw Blame History

Issue Reporting / Suggestions

The easiest way to help is to provide feedback using the GitHub issues page. Most of libtcod's tasks are organized here.

Python specific issues should go to the python-tcod issues page.

Documentation

The current setup for doc generation is by using Breathe to add Sphinx directives for Doxygen's documentation style.

The docs directory has instructions on how to build the documentation. This isn't strictly necessary, but it can help with larger documentation tasks.

Newer C/C++ documentation on functions should generally try to follow this format:

/***************************************************************************
    @brief [Brief summary]

    @details [Extended description]

    @param value Description of parameter.
    @return Description of the return value if any.

    @code{.cpp}
      // Code example if necessary.
    @endcode
    \rst
    .. versionadded:: Unreleased
    \endrst
 */
int example(int value);

Functions which are expected to always be documented are the public functions in headers, and the static functions in sources.

Building libtcod for Development

The easiest and recommended build method is to use the Visual Studio Code with the CMake Tools extension. This automates a significant portion of the build process.

Code formatting is handled via clang-format and EditorConfig, make sure your IDE supports these tools.

Visual Studio Code

This is the common setup for developing libtcod on Windows. It should also work on all platforms. Dependencies are installed using Vcpkg and CMake is invoked by Visual Studio Code.

Install Visual Studio Community's desktop C++
Install Visual Studio Code.
Install LLVM and make sure it's added to your PATH.
Clone the libtcod repository and its submodules.
In Visual Studio Code choose File -> Open folder... then select the libtcod repository.
Install the extensions recommended for this workspace.
CMake Tools will ask permission to configure the project, select yes.
When CMake Tools asks for a kit, the recommended option is: Visual Studio Community 2019 Release - amd64
When CMake Tools asks for a launch target. Scroll down and pick samples_cpp.

The status bar at the bottom of Visual Studio Code can be used to configure CMake Tools.

You can now run the samples project from the IDE. Other launch targets like samples_c or unittest may be useful choices. If you set libtcod as the build target you could check libtcod for compile errors without having to build and run the samples too.

MacOS / Linux

For MacOS and Linux you should be able to compile libtcod easily from the command line. See the instructions in the relevant buildsys subfolder.

Some compilation methods, including SCons (Windows, Linux, MacOS) and Autotools (Linux, MacOS), are located within the buildsys/ subdirectory.

SCons automatically downloads SDL2 and can be used on all platforms. Instructions are provided here. The current release builds are built using SCons.

Autotools is a common standard on Linux, and can be used for MacOS. Instructions are provided here.

CMake

The libtcod repository includes a CMake script for compiling libtcod and its tests and samples. You can include the repository as a submodule allowing another project to build and run any version of libtcod.

By default it is assumed that Vcpkg will be used to get dependencies, but this can be changed by setting the following cache variables. find_package means CMake's find_package command will be used. vendored means that sources bundled in the repository will be statically compiled, this is generally not recommended. conan and vcpkg means that package manager specific scripts are used to link these dependencies. disable can be used to ignore a library, but functions which require that library will no longer function.

Cache Variable	Default	Options	Notes
LIBTCOD_SDL2	find_package	conan, disable, find_package	Support for libtcod contexts.
LIBTCOD_ZLIB	find_package	conan, disable, find_package	Support for REXPaint and TCODZip.
LIBTCOD_LODEPNG	find_package	disable, find_package, vendored
LIBTCOD_UTF8PROC	vcpkg	disable, find_package, vcpkg	Support for console printing functions.
LIBTCOD_STB	find_package	find_package, vendored
LIBTCOD_THREADS	false	bool	Support for deprecated functions, leave this off.

5.1 KiB Raw Blame History