From c2945f23969122cd1a1ffe3640e49e81c0c1c65d Mon Sep 17 00:00:00 2001 From: Lephenixnoir Date: Thu, 28 Jan 2021 18:17:20 +0100 Subject: [PATCH] add README --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0c4a11d --- /dev/null +++ b/README.md @@ -0,0 +1,44 @@ +# 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)` 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](https://gitea.planet-casio.com/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 (in French) (TODO: link once published) 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 two variables to help you install your files: + +* `FXSDK_COMPILER_INSTALL` is the install path for the compiler (`sh-elf-gcc -print-search-dirs`), the libraries go there and the headers in the `include` subfolder. +* `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 versions, 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 applied automatically. Whenever you update your library, the library file or the find module will change and all user applications will automatically relink. + +## GiteaPC support + +[GiteaPC](https://gitea.planet-casio.com/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` 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`), just remember to add the file in `.gitignore` as it will be otherwise ignored. See [sh-elf-gcc](https://gitea.planet-casio.com/Lephenixnoir/sh-elf-gcc) for an example of custom configuration. + +## 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)).