From fe79f01fa336b16317507178640e7b6a7ae83cb3 Mon Sep 17 00:00:00 2001 From: methylDragon Date: Mon, 27 Jun 2022 16:26:39 -0700 Subject: [PATCH 1/5] Migrate some docs and project names in macros Signed-off-by: methylDragon --- Changelog.md | 7 +- MigrationFromClassic.md | 94 ++++++++++++------------ README.md | 22 +++--- api.md.in | 4 +- cmake/Export.hh.in | 2 +- cmake/IgnConfigureBuild.cmake | 2 +- cmake/IgnConfigureProject.cmake | 2 +- cmake/IgnCreateDocs.cmake | 2 +- cmake/IgnPackaging.cmake | 6 +- cmake/IgnSetCompilerFlags.cmake | 2 +- cmake/pkgconfig/ignition-component.pc.in | 2 +- cmake/pkgconfig/ignition.pc.in | 2 +- config/ignition-cmake-config.cmake.in | 18 ++--- config/ignition-cmake.pc.in | 4 +- examples/find_ogre2/README.md | 2 +- tutorials.md.in | 4 +- tutorials/developing_with_ign-cmake.md | 12 +-- tutorials/index.md | 2 +- tutorials/install.md | 31 ++++---- 19 files changed, 109 insertions(+), 111 deletions(-) diff --git a/Changelog.md b/Changelog.md index b9351947..c7b83dfa 100644 --- a/Changelog.md +++ b/Changelog.md @@ -101,7 +101,7 @@ 1. User-friendly skip component warning * [Pull request #165](https://github.com/gazebosim/gz-cmake/pull/165) -1. Run ign-cmake's copy of check_test_ran +1. Run gz-cmake's copy of check_test_ran * [Pull request #168](https://github.com/gazebosim/gz-cmake/pull/168) ### Gazebo CMake 2.7.0 (2021-03-30) @@ -157,10 +157,10 @@ 1. Remove deprecated doxygen configurations * [Pull request 136](https://github.com/gazebosim/gz-cmake/pull/136) -1. Generate doxygen tutorials for ign-cmake +1. Generate doxygen tutorials for gz-cmake * [Pull request 137](https://github.com/gazebosim/gz-cmake/pull/137) -1. Enable make codecheck for ign-cmake +1. Enable make codecheck for gz-cmake * [Pull request 138](https://github.com/gazebosim/gz-cmake/pull/138) 1. Generate valid visibility macros by replacing hyphens in component name @@ -387,4 +387,3 @@ * [Full list of changes](https://github.com/gazebosim/gz-cmake/compare/ignition-cmake_0.4.1...ignition-cmake_0.4.0) ### Gazebo CMake 0.4.0 - diff --git a/MigrationFromClassic.md b/MigrationFromClassic.md index 15a054c8..a79f5724 100644 --- a/MigrationFromClassic.md +++ b/MigrationFromClassic.md @@ -1,24 +1,24 @@ # Migration Instructions (from Gazebo classic) -This file provides instructions for `ignition` library developers to adopt the -`ignition-cmake` package into their own library's build system. This document -is primarily targeted at ignition libraries that existed before `ignition-cmake` -was available, but it might also be useful for getting a new `ignition` project +This file provides instructions for `Gazebo` library developers to adopt the +`gz-cmake` package into their own library's build system. This document +is primarily targeted at Gazebo libraries that existed before `gz-cmake` +was available, but it might also be useful for getting a new `Gazebo` project started. The first section goes over changes that your library **must** make in order to -be compatible with `ignition-cmake`. The second section mentions some utilities -provided by `ignition-cmake` which might make your project's CMake scripts more +be compatible with `gz-cmake`. The second section mentions some utilities +provided by `gz-cmake` which might make your project's CMake scripts more clean and maintainable, but use of those utilities is not required. The third section details some of the new CMake features that we'll be using through -`ignition-cmake` and explains why we want to use those features. The last +`gz-cmake` and explains why we want to use those features. The last section describes some CMake anti-patterns which we should aggressively avoid as we move forward. # 1. Required Changes -You can find examples of projects that have been set up to use `ign-cmake` in -the repos of `ign-common` (branch: `CMakeRefactor`) and `ign-math` +You can find examples of projects that have been set up to use `gz-cmake` in +the repos of `gz-common` (branch: `CMakeRefactor`) and `gz-math` (branch: `CMakeRefactor-3`). The following is a checklist to help you make sure your project is migrated properly. @@ -30,14 +30,14 @@ That's right, just throw it all out. We're migrating to 3.10 because it provides many valuable features that we are now taking advantage of. -### Then call `find_package(ignition-cmake3 REQUIRED)` +### Then call `find_package(gz-cmake3 REQUIRED)` -This will find `ignition-cmake` and load up all its useful features for you. +This will find `gz-cmake` and load up all its useful features for you. ### Then call `gz_configure_project( )` This is a wrapper for cmake's native `project(~)` command which additionally -sets a bunch of variables that will be needed by the `ignition-cmake` macros and +sets a bunch of variables that will be needed by the `gz-cmake` macros and functions. ### Then search for each dependency using `gz_find_package(~)` @@ -56,7 +56,7 @@ A variety of arguments are available to guide the behavior of `gz_find_package(~)`. Most of them will not be needed in most situations, but you should consider reading them over once just in case they might be relevant for you. The macro's documentation is available in -`ign-cmake/cmake/IgnUtils.cmake` just above definition of `gz_find_package(~)`. +`gz-cmake/cmake/IgnUtils.cmake` just above definition of `gz_find_package(~)`. Feel free to ask questions about any of its arguments that are unclear. Any operations that might need to be performed while searching for a package @@ -66,7 +66,7 @@ information on writing find-modules. ### Then call `gz_configure_build(~)` This macro accepts the argument `QUIT_IF_BUILD_ERRORS` which you should pass to -it to get the standard behavior for the ignition projects. If for some reason +it to get the standard behavior for the Gazebo projects. If for some reason you want to handle build errors in your own way, you can leave that argument out and then do as you please after the macro finishes. @@ -77,7 +77,7 @@ listed below must be applied throughout your directory tree. ### Change instances of `PROJECT__VERSION` variables to `PROJECT_VERSION_`. -In the original ignition CMake scripts, we define variables for the components +In the original Gazebo CMake scripts, we define variables for the components of the library version: `PROJECT_MAJOR_VERSION`, `PROJECT_MINOR_VERSION`, and `PROJECT_PATCH_VERSION`. While there is nothing inherently wrong with these variable names, in CMake 3+ the `project(~)` command automatically defines the @@ -91,7 +91,7 @@ to embrace the "single source of truth" pattern. ### Change instances of `IGN_PROJECT_NAME` to `IGN_DESIGNATION` We've had a variable called `IGN_PROJECT_NAME` which refers to the `` -in the `ignition-` name of each project. I felt that the name of the +in the `gz-` name of each project. I felt that the name of the variable was too similar to the `PROJECT_NAME` variable that is automatically defined by CMake, as well as the `PROJECT_NAME[_NO_VERSION][_UPPER/_LOWER]` that we define for convenience. Instead of referring to both as `[IGN_]PROJECT_NAME`, @@ -122,12 +122,12 @@ requires a certain standard, it MUST be specified directly to this function in order to ensure that the requirement gets correctly propagated into the project's package information so that dependent libraries will also be aware of the requirement. See the documentation of `gz_create_core_library(~)` in -`ign-cmake/cmake/IgnUtils.cmake` for more details on how to specify your +`gz-cmake/cmake/IgnUtils.cmake` for more details on how to specify your library's C++ standard requirement. ### Specify `TYPE` and `SOURCES` arguments in `gz_build_tests(~)` -Previously, ignition libraries would set a `TEST_TYPE` variable before calling +Previously, Gazebo libraries would set a `TEST_TYPE` variable before calling `gz_build_tests(~)`, and that variable would be used by the macro to determine the type of tests it should create. This resulted in some anti-patterns where the `TEST_TYPE` variable would be set somewhere far away from the call to @@ -160,7 +160,7 @@ Also note that all of the "interface include directories" of any targets that you pass to `LIB_DEPS` will automatically be visible to all the tests, so this tag should be even less commonly needed than `LIB_DEPS`. -### Move your project's `cmake/config.hh.in` file to `include/ignition//config.hh.in` +### Move your project's `cmake/config.hh.in` file to `include/gz//config.hh.in` The `config.hh.in` file has traditionally lived in the `cmake` subdirectory of each project, but that subdirectory should be deleted at the end of the @@ -211,9 +211,9 @@ names of libraries. When an item containing `::` is passed to and it will throw an error and quit if that target is not found, instead of failing quietly or subtly. Therefore, we should always exercise the practice of using `::` in the names of any imported targets that we intend to use. -`ignition-cmake` will automatically export all ignition library targets to have -the name `ignition-::ignition-` -(for example, `ignition-common0::ignition-common0`). When creating a cmake +`gz-cmake` will automatically export all Gazebo library targets to have +the name `gz-::gz-` +(for example, `gz-common0::gz-common0`). When creating a cmake find-module, the macro `gz_import_target(~)` should be used generate an imported target which follows this convention. More about creating find-modules can be found in the section on anti-patterns. @@ -223,13 +223,13 @@ can be found in the section on anti-patterns. Calling `gz_create_core_library()` will also take care of installing the library. Simply remove this function from your cmake script. -### Replace calls to `#include "ignition//System.hh"` with `#include "ignition//Export.hh"`, and delete the file `System.hh`. +### Replace calls to `#include "gz//System.hh"` with `#include "gz//Export.hh"`, and delete the file `System.hh`. -Up until now, we've been maintaining a "System" header in each ignition library. +Up until now, we've been maintaining a "System" header in each Gazebo library. This is being replaced by a set of auto-generated headers, because some of the individual projects' implementations had errors or issues in them. The new auto-generated headers will enforce consistency and compatibility across all of -the ignition projects. The header is also being renamed because the role of the +the Gazebo projects. The header is also being renamed because the role of the header is to provide macros that facilitate exporting the library, therefore it seems more appropriate to name it "Export" instead of "System". Nothing in the header is interacting with the operating system, so the current name feels like @@ -237,28 +237,28 @@ somewhat of a misnomer (presumably the name "System" came from the fact that the macros are system-dependent, but I think naming the header after the role that it's performing would be more appropriate). -### Replace `IGNITION_