# libexample: A template gint library using CMake This repository is a (Gitea template) example of how to build a library to use with [gint](/Lephenixnoir/gint). It uses the CMake build system added in [fxSDK 2.3](/Lephenixnoir/fxsdk). 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 ``, 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](/Lephenixnoir/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](https://www.planet-casio.com/Fr/forums/topic16647-1-tutoriel-compiler-des-add-ins-avec-cmake-fxsdk.html) (in French) for an introduction to CMake in the context of add-ins. You might be interested in [`configure_file()`](https://cmake.org/cmake/help/latest/command/configure_file.html) and [`install()`](https://cmake.org/cmake/help/latest/command/install.html), 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.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`](/Lephenixnoir/fxsdk/src/branch/master/fxsdk/cmake/FindSimpleLibrary.cmake) module. ## GiteaPC support [GiteaPC](/Lephenixnoir/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](https://gitlab.kitware.com/cmake/community/-/wikis/FAQ#can-i-do-make-uninstall-with-cmake), 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-.cmake` (they can be installed with `giteapc install Lephenixnoir/Template-gint-library:name`). See [sh-elf-gcc](/Lephenixnoir/sh-elf-gcc) for an example of custom configurations. ## License All the files in this repository are [licensed under CC0](https://creativecommons.org/publicdomain/zero/1.0/); you can use them in any way you want under no conditions whatsoever (this is compatible with the GPL : [[1]](https://wiki.creativecommons.org/wiki/CC0_FAQ#May_I_apply_CC0_to_computer_software.3F_If_so.2C_is_there_a_recommended_implementation.3F), [[2]](https://www.gnu.org/licenses/license-list.html#PublicDomain)).