libarcade

libarcade is a header-only C++20 interface library for Epitech’s second-year Arcade project.

Installing the library

It is recommended you install the library as follows:

project_directory/
 |--> lib/
       |--> libarcade/
       |--> ... (other libraries)
 |--> src/
       |--> ... (src files / directories)
 |--> ... (other files/directories)

Note

Whilst this is file structure is recommended, you are free to do whatever you prefer; it’s your project after all.

To programmatically install your library, all you need to do is include the following commands in your Makefile or CMakeLists.txt:

rm -rf lib/libarcade/
git clone 'git@github.com:Bard-Gaming/libarcade.git' lib/libarcade/
make -C lib/libarcade/ no-repo

As well as adding the directory to your include directories using the -I compiler flag:

-Ilib/libarcade/

For instance, you could add the following in a Makefile:

LIB_DIR = lib
LIB_ARCADE = $(LIB_DIR)/libarcade

CFLAGS += -I$(LIB_ARCADE)

$(LIB_ARCADE)/Arcade.hpp:
	@printf "\033[32m%s\033[0m\n" "installing libarcade..."
	@rm -rf $(LIB_ARCADE)
	@git clone 'git@github.com:Bard-Gaming/libarcade.git' $(LIB_ARCADE)
	@make -C $(LIB_ARCADE) no-repo
	@printf "\033[32m%s\033[0m\n" "successfully installed libarcade"

Important

If you choose a file structure different from the one described above, don’t forget to modify the paths (namely lib/arcade/) in the aforementioned commands.

If everything was set up properly, you should be able to use the library in your project:

#include <Arcade.hpp>

/**
 * Program entry
 */
int main()
{
    Arcade::IDisplay* display = get_display();
    ...
}

Shared library entrypoints

If you wish to make a shared library using libarcade, you must define one of the following entrypoints.

The rationale between having two different names for the entrypoints is to be able to identify whether your library is a display library or a game library, without having to rely on the name of your library.

Display libraries

Display libraries must prototype their entrypoints as follows:

Arcade::IDisplay* get_display();

Important

Don’t forget to wrap your entrypoint in an extern "C" block. This is required.

Game libraries

Game libraries must prototype their entrypoints as follows:

Arcade::IGame* get_game();

Important

As with display libraries, don’t forget to wrap your entrypoint in an extern "C" block. This is required.

Loading libraries

The point of standardising these entrypoints is to be able to invoke them using libdl.

When doing so, you may use the types and constants defined in libarcade, but this is not a requirement.

Example:

#include <Arcade/utils.hpp>  // for GameEntryPointFnc type
                             // and GAME_ENTRYPOINT constant

Arcade::GameEntryPointFnc fnc = ::dlsym(..., GAME_ENTRYPOINT);
Arcade::IGame* game = fnc();

Note

The code shared above will not work as-is. The purpose of the example is to show the overall steps one might take in order to tap into a library’s entrypoint.

Library structure

The library is structured as follows:

lib_root/
 |--> Arcade.hpp  (utility header file that contains everything)
 |--> Arcade
       |--> display.hpp  (for everything related to displays)
       |--> game.hpp     (for everything related to games)
       |--> utils.hpp    (general implementation utilities)

Note

The library may add or remove header files from the Arcade/ directory.

However, the headers shown above will never be removed, so you may use the all throughout your project without having to worry about future incompatibilities.

Contributing

Contributions are done through Pull Requests. The title of the pull requests should (preferably) be Conventional Commits-compliant. If they aren’t, they will most likely modified to be.

Branches must follow the same idea: if you’re working on the addition of a new utility, you should name your branch something along the lines of feat/my-new-util.

Important

Branches that don’t start with feat/, fix/, docs/, refactor/, etc… can’t be pushed to the repository.

Contributions are first merged into the unstable branch until a full release is done. If you depend on your contribution to continue work, please add the important label to your pull request.

If you wish to stay up-to-date with the latest additions, you may stay on the unstable branch, but this isn’t recommended, as it may break your project during active development (features might get added, then removed on a subsequent patch; generally speaking you should consider everything from the unstable branch as a volatile mess).