A template repository for gint libraries to build with CMake.
Go to file Use this template
Lephenixnoir c34bd65859
update tutorial and CMake files for fxSDK 2.9
2022-08-21 10:09:59 +02:00
cmake update tutorial and CMake files for fxSDK 2.9 2022-08-21 10:09:59 +02:00
include/example (irrelevant changes) 2021-01-28 17:38:27 +01:00
src base library and build system 2021-01-28 17:32:57 +01:00
.gitignore update tutorial and CMake files for fxSDK 2.9 2022-08-21 10:09:59 +02:00
CMakeLists.txt update tutorial and CMake files for fxSDK 2.9 2022-08-21 10:09:59 +02:00
README.md update tutorial and CMake files for fxSDK 2.9 2022-08-21 10:09:59 +02:00
giteapc.make fix uninstall commands for sh-based OSes 2021-01-29 19:06:24 +01:00

README.md

libexample: A template gint library using CMake

This repository is a (Gitea template) example of how to build a library to use with gint. It uses the CMake build system added in fxSDK 2.3.

Here's how the files are used:

  • src and include are your library's code and headers. Unless you have a single header, you'll want to keep the compiler's include folder clean and have all your headers included as <example/header.h>, so include has a single subfolder example.
  • There is a template header at include/example/config.h.in that gets transformed by CMake during build to insert the version number without hardcoding it. You can use it for other compile-time options.
  • CMakeLists.txt is a pretty standard CMake script that builds the library.
  • cmake/FindLibExample.cmake is a script for add-ins using your library, so that they can find_package(LibExample 1.0) and get all the compile and link options for free.
  • giteapc.make makes it possible to build and install your library in a simple command using GiteaPC. If you don't want that you can delete it (along with the related .gitignore entries).

The build system

Not a lot to discuss here, this is pretty standard. See the tutorial on Planète Casio (in French) for an introduction to CMake in the context of add-ins. You might be interested in configure_file() and install(), which are rarely used in add-ins.

The fxSDK provides three variables to help you install your files:

  • FXSDK_LIB is the install path for library files (*.a).
  • FXSDK_INCLUDE is the install path for headers (*.h); we use a subfolder example/ to keep things organized.
  • FXSDK_CMAKE_MODULE_PATH is the path of an fxSDK folder storing built-in and user-provided CMake modules. These are made visible to anyone that configures with fxsdk build-{fx,cg}.

The FindPackage file

cmake/FindLibExample.cmake is a module used to search for libexample. The user would request to find_package(LibExample) and CMake will look for various options, one of which is a Find<Package>.cmake file in one of the search directories.

The goal of a find module is to determine whether the library is available, its version, and there are a couple of options. Most of these are handled by find_package_handle_standard_args(), including checking that the user-requested version and the installed version are compatible.

If the library is found, the find module defines an external target (called "imported") that provides the path to the library and suitable compile and link options. The user can run target_link_libraries(addin LibExample::LibExample) and all the flags will be supplied automatically. Whenever you update your library, the library file or the find module will change and all user applications will automatically relink.

The detection step is here automated with the fxSDK's FindSimpleLibrary.cmake module.

GiteaPC support

GiteaPC is a tool to automate building and installing repositories from the Planète Casio Gitea forge. It was designed to speed up library management in the fxSDK. A repository that has the giteapc topic (topics can be added through the "Manage topics" link on the repository's front page) and provides giteapc.make can be built, installed, and updated with a simple command.

% giteapc install Lephenixnoir/Template-gint-library

The job of giteapc.make is simply to provide configure, build, install and uninstall commands. CMake does not support uninstall targets, but we can simply remove the files that CMake has recorded installing. This might leave empty directories, but it's a good start.

giteapc.make can also specify basic dependencies in the top comment.

The giteapc-config.make file is for the user to customize the build by adding environment variables (such as setting LIBEXAMPLE_CMAKEOPTS_FX to change compiler behaviour, or anything they might need). You can provide configurations of your own in giteapc-config-<name>.cmake (they can be installed with giteapc install Lephenixnoir/Template-gint-library:name). See sh-elf-gcc for an example of custom configurations.

License

All the files in this repository are licensed under CC0; you can use them in any way you want under no conditions whatsoever (this is compatible with the GPL : [1], [2]).