Skip to content

Getting Started

Jump to bottom
Julien SOYSOUVANH edited this page May 16, 2022 · 8 revisions

Index

Integrate Refureku in your program

Concrete integration examples with CMake and Visual Studio are available in this repository (/LibraryIntegration).

Get the binaries

First of all, get the latest binaries available for your platform, or build Refureku from source. Binaries are available for Windows, Linux and MacOS in the Releases section of the Github repository.

Project settings

This step-by-step tutorial shows how to proceed with CMake, but it can be translated to any build system.

  1. First, make sure you compile in C++17 or later:
target_compile_features(MyAmazingProgram PUBLIC cxx_std_17)
  1. Add Refureku headers:
target_include_directories(MyAmazingProgram PUBLIC Path/To/Refureku/Include)
  1. Link against Refureku:
target_link_directories(MyAmazingProgram PRIVATE Path/To/Refureku/Bin)
target_link_libraries(MyAmazingProgram PRIVATE Refureku)
  1. Make a custom event in your build system to run the Refureku code generator before each compilation:
add_custom_target(RunRefurekuGenerator
	WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}  #PROJECT_SOURCE_DIR is the path to the directory containing the Cmake with the project command
	COMMAND Path/To/RefurekuGenerator Path/To/RefurekuSettings.toml)

add_dependencies(MyAmazingProgram RunRefurekuGenerator)

Note: A template RefurekuSettings.toml file is distributed in the binaries, and is also available in the git repository.

  1. (Linux only) On Linux systems, the shipped libclang.so library used by the code generator has other dependencies that might not be installed on your machine, resulting in an error when compiling/running the generator. Installing the missing libraries using the apt-get install command should fix the problem.

Generator configuration

The Refureku code generator shipped with the binaries uses the configuration stored in the RefurekuSettings.toml file to generate appropriate code for your program. If you want to customize further the generation process, you might want to integrate the code generator yourself.

The provided template contains all the available properties, but we are going to focus on the ones that MUST be set to enable reflection in our project, from top to bottom.

Note: All the paths must be written between ''' '''' and must be absolute or relative to your working directory specified in the previous step (add_custom_target command in CMake).

  1. toProcessDirectories: A list of directories containing files with reflected entities. Just add your main include directory.
toProcessDirectories = [ '''./Include''' ] #Replace by the path to your include project's main include directory.

Note: If your project contains a lot of non-reflected files, you might want to group all your reflected files in specific directories and use them in place of your global include directory to speed up the code generation process.

  1. ignoredDirectories: A list of directories the generator should ignore. It is common to always ignore the output directory since we don't want to generate code for the generated code itself.
ignoredDirectories = [ '''./Include/Generated''' ]
  1. outputDirectory: Directory in which the generator output files will be generated.
outputDirectory = '''./Include/Generated'''
  1. projectIncludeDirectories: A list of all your project include directories. This list MUST absolutely contain all of your project include directories, or the generation will fail.
projectIncludeDirectories = [
  '''./Include''', #Our project include directory
  '''./Path/To/Refureku/Include'''  #Refureku include directory
]
  1. compilerExeName: The compiler you are using to compile your program. Can be one of msvc, clang++ or g++. You can target a specific version of clang++ or g++, the only requirement being that it is a valid command when used in a terminal.
compilerExeName = "clang++"

Integration test

Before running your program, make sure that the Refureku dynamic library is in a suitable directory (typically next to your executable), and that libclang is next to the RefurekuGenerator. Additionally, Windows users should make sure vswhere.exe is next to the RefurekuGenerator as well.

We should be ready to test the integration! Add the following test file in your include directory:

//IntegrationTest.h
#include "Generated/IntegrationTest.rfkh.h"

enum class ENUM() IntegrationTest {}

File_IntegrationTest_GENERATED

And in your main file:

#include <cassert>

#include "Generated/IntegrationTest.rfks.h"

int main()
{
  assert(rfk::getDatabase().getFileLevelEnumByName("IntegrationTest") != nullptr);

  return 0;
}

If any problem occurs, make sure to check the build logs to track any warning / error issued by the code generator. If it doesn't help, you can open an issue here.

Build Refureku from source

Requirements:

  • CMake 3.15.0+
  • A compatible compiler: MSVC Platform Toolset v141+ / GCC8.0.0+ / Clang 7.0.0+.

Clone the repository

Clone the git repository with its submodules:

> git clone --recurse-submodules https://github.com/jsoysouvanh/Refureku.git
>
> cd Refureku

Generate the project

> cmake -B Build/Release -DCMAKE_BUILD_TYPE=Release -G "<Generator>"

Note: If you don't plan to run tests, you can add the -DBUILD_TESTING=OFF cmake option to build faster (the googletests dependency won't be fetched).

Most common generators include:

  • Visual Studio 15 2017
  • Visual Studio 16 2019
  • Unix Makefiles
  • Ninja
  • Type cmake -G for more information

Note: If you use Visual Studio generator, the default target platform may vary so you should specify it explicitly. See the generator documentation for more information.

> cmake -B Build/Release -DCMAKE_BUILD_TYPE=Release -G "Visual Studio 16 2019" -A x64

Build the library and code generator

> cmake --build Build/Release --config Release --target RefurekuGenerator Refureku

You will find built executables / shared libraries in Refureku/Build/Release/Bin and static libraries in Refureku/Build/Release/Lib.

(optional) Run the tests

> cmake --build Build/Release --config Release --target RefurekuTests
>
> cd Build/Release
> ctest -C Release -V -R RefurekuTests

Note: The RefurekuTests target does not exist if you specified the -DBUILD_TESTING=OFF when generating the project. If you want to run tests, regenerate the project without this flag.

Home

Clone this wiki locally