Merge branch 'gz-physics8' into physics_plugins

CMakeLists.txt

@@ -16,7 +16,7 @@ find_package(gz-cmake4 REQUIRED)
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
-gz_configure_project(VERSION_SUFFIX pre2)
+gz_configure_project(VERSION_SUFFIX)
 
 #============================================================================
 # Set project-specific options

Changelog.md

@@ -1,9 +1,20 @@
 ## Gazebo Physics 8.x
 
-### Gazebo Physics 8.0.0 (2024-09-XX)
+### Gazebo Physics 8.0.0 (2024-09-25)
 
 1. **Baseline:** this includes all changes from 7.3.0 and earlier.
 
+1. Miscellaneous documentation fixes
+    * [Pull request #691](https://github.com/gazebosim/gz-physics/pull/691)
+    * [Pull request #689](https://github.com/gazebosim/gz-physics/pull/689)
+    * [Pull request #690](https://github.com/gazebosim/gz-physics/pull/690)
+    * [Pull request #688](https://github.com/gazebosim/gz-physics/pull/688)
+    * [Pull request #686](https://github.com/gazebosim/gz-physics/pull/686)
+    * [Pull request #684](https://github.com/gazebosim/gz-physics/pull/684)
+    * [Pull request #683](https://github.com/gazebosim/gz-physics/pull/683)
+    * [Pull request #682](https://github.com/gazebosim/gz-physics/pull/682)
+    * [Pull request #681](https://github.com/gazebosim/gz-physics/pull/681)
+
 1. Remove deprecated functions
     * [Pull request #673](https://github.com/gazebosim/gz-physics/pull/673)
 

README.md

@@ -79,27 +79,33 @@ Please refer to the [examples directory](https://github.com/gazebosim/gz-physics
 
 API and tutorials can be found at [https://gazebosim.org/libs/physics](https://gazebosim.org/libs/physics).
 
-You can also generate the documentation from a clone of this repository by following these steps.
+On Ubuntu, you can also generate the documentation from a clone of this repository by following these steps.
 
-1. You will need Doxygen. On Ubuntu Doxygen can be installed using
+1. You will need Doxygen, which can be installed using
 
     ```
     sudo apt-get install doxygen
     ```
 
-2. Clone the repository
+2. Install dependencies
+   ```
+   sudo apt-add-repository -s "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -c -s) main"
+   sudo apt-get build-dep -y libgz-physics8-dev
+   ```
+
+3. Clone the repository
 
     ```
     git clone https://github.com/gazebosim/gz-physics -b gz-physics8
     ```
 
-3. Configure and build the documentation.
+4. Configure and build the documentation.
 
     ```
-    cd gz-physics; mkdir build; cd build; cmake ../; make doc
+    cd gz-physics; mkdir build; cd build; cmake ..; make doc
     ```
 
-4. View the documentation by running the following command from the build directory.
+5. View the documentation by running the following command from the build directory.
 
     ```
     firefox doxygen/html/index.html
@@ -109,7 +115,7 @@ You can also generate the documentation from a clone of this repository by follo
 
 Follow these steps to run tests and static code analysis in your clone of this repository.
 
-1. Follow the [source install instruction](#source-install).
+1. Follow the "Source Installation" instructions in the [installation tutorial](https://gazebosim.org/api/physics/8/installation.html).
 
 2. Run tests.
 
@@ -132,19 +138,21 @@ gz-physics
 ├── bullet                    Files for bullet plugin component.
 ├── bullet-featherstone       Files for bullet-featherstone plugin component.
 ├── dartsim                   Files for dartsim plugin component.
-├── example                   Examples about how to use the library
+├── examples                  Examples about how to use the library.
 ├── heightmap                 Heightmap related header files.
 ├── include/gz/physics        Header files.
 ├── mesh                      Files for mesh component.
-├── resources                 Model and mesh resource files used by tests.
 ├── sdf                       Files for sdf component.
 ├── src                       Source files and unit tests.
 ├── test
 │    ├── benchmark            Benchmark tests.
+│    ├── common_test          Tests common to multiple physics plugins.
+│    ├── include              Header files for tests.
 │    ├── integration          Integration tests.
 │    ├── performance          Performance tests.
 │    ├── plugins              Plugins used in tests.
 │    ├── regression           Regression tests.
+│    ├── resources            Models and mesh resource files.
 │    └── static_assert        Tests involving compilation failures.
 ├── tpe
 │    ├── lib                  Implementation of TPE engine.
@@ -164,7 +172,7 @@ Please see
 
 # Versioning
 
-This library uses [Semantic Versioning](https://semver.org/). Additionally, this library is part of the [Gazebo project](https://gazebosim.org) which periodically releases a versioned set of compatible and complimentary libraries. See the [Gazebo website](https://gazebosim.org) for version and release information.
+This library uses [Semantic Versioning](https://semver.org/). Additionally, this library is part of the [Gazebo project](https://gazebosim.org) which periodically releases a versioned set of compatible and complementary libraries. See the [Gazebo website](https://gazebosim.org) for version and release information.
 
 # License
 

tutorials/02_installation.md

@@ -83,11 +83,8 @@ system requirements.
 
 ## Binary Installation
 
-1. Install Homebrew, which should also prompt you to install the XCode
-command-line tools:
-  ```
-  ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-  ```
+1. Install [Homebrew](https://brew.sh/), which should also prompt you to install the XCode
+command-line tools.
 
 2. Run the following commands
   ```

tutorials/08-implementing-a-custom-feature.md

@@ -49,14 +49,13 @@ Looking closer to a plugin folder, for example, the `dartsim` (DART) plugin:
 dartsim
 ├── worlds                            Example SDF files for testing dartsim plugin functionalities.
 ├── src                               Main implementation files of the plugin features interfacing the physics engines API
-├── include/gz/physics/dartsim  Header files for the plugin features.
 └── CMakeLists.txt                    CMake plugin build script.
 ```
 
 Basically, new implementation of \ref gz::physics::Feature "Feature" or
 \ref gz::physics::FeatureList "FeatureList", which is corresponded to a
 functionality of the external physics engine can be defined as a header in
-`include/gz/physics/<plugin_name>` folder. The custom feature could
+`src` folder. The custom feature could
 be added in a \ref gz::physics::FeatureList "FeatureList"
 and implemented its functionalities in `src` folder.
 
@@ -82,7 +81,7 @@ downstream physics plugins.
 
 For custom feature requirements, there are two main component classes
 in the general structure of a custom feature:
-- \ref gz::physics::Entity "Entity" corresponds to the "proxy object" that
+- \ref gz::physics::Entity "Entity" corresponds to the "proxy object" where
 the \ref gz::physics::Feature "Feature" is implemented. These are the most
 common "proxy objects" that are inherited from `Entity` class:
   - \ref gz::physics::Feature::Engine "Engine": Placeholder class for the
@@ -134,9 +133,9 @@ will not run at the same time when requested.
 
 ### Define custom feature template
 
-With the requirements and restrictions above, we first need to define a feature template for the custom feature. In this case, this feature will be responsible for retrieving world pointer from the physics engine. The template is placed in [World.hh](https://github.com/gazebosim/gz-physics/blob/main/dartsim/include/gz/physics/dartsim/World.hh):
+With the requirements and restrictions above, we first need to define a feature template for the custom feature. In this case, this feature will be responsible for retrieving world pointer from the physics engine. The template is placed in [World.hh](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/World.hh):
 
-\snippet dartsim/include/gz/physics/dartsim/World.hh feature template
+\snippet dartsim/src/World.hh feature template
 
 The `RetrieveWorld` feature retrieves
 world pointer from physics engine, so we will use the `World` entity inherited
@@ -159,9 +158,8 @@ dartsim
 ├── src
 │    ├── CustomFeatures.hh
 │    ├── CustomFeatures.cc
+|    ├──  World.hh
 │    └── ...
-├── include/gz/physics/dartsim
-│    └──  World.hh
 └── CMakeLists.txt
 ```
 
@@ -178,24 +176,24 @@ After defining the feature template, we can add it to a custom
 The custom feature `RetrieveWorld` is added to `CustomFeatureList`, other custom
 features could also be added here.
 The `CustomFeatures` "FeatureList" here uses data structures and classes from:
-- [Base.hh](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/Base.hh), which defines structures that contain information to create `Model`, `Joint`, `Link`, and `Shape` objects in Dartsim API.
+- [Base.hh](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/Base.hh), which defines structures that contain information to create `Model`, `Joint`, `Link`, and `Shape` objects in Dartsim API.
 They act as an interface between Gazebo Physics Library and the actual physics engine.
 - \ref gz::physics::Implements3d "Implements3d" for implementing the
 custom feature with \ref gz::physics::FeaturePolicy3d "FeaturePolicy3d"
 ("FeaturePolicy" of 3 dimensions and scalar type `double`).
 
-We will then implement the actual function with Dartsim API in [CustomFeatures.cc](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/CustomFeatures.cc) to override the member function
+We will then implement the actual function with Dartsim API in [CustomFeatures.cc](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/CustomFeatures.cc) to override the member function
 declared in the custom feature header file:
 
 \snippet dartsim/src/CustomFeatures.cc implementation
 
 Here, we implement the behavior of `GetDartsimWorld` with Dartsim API to return the
 world pointer from `EntityStorage` object storing world pointers of `dartsim` in
-[Base](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/Base.hh) class.
+[Base](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/Base.hh) class.
 
 In the end, we add the implemented `CustomFeatures` "FeatureList" together with
 other \ref gz::physics::FeatureList "FeatureList" to final `DartsimFeatures`
-"FeatureList" as in [dartsim/src/plugin.cc](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/plugin.cc)
+"FeatureList" as in [dartsim/src/plugin.cc](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/plugin.cc)
 (please see the \ref createphysicsplugin "Implement a physics feature" tutorial
 for registering the plugin to Gazebo Physics).
 
@@ -208,6 +206,5 @@ dartsim
 │    ├── CustomFeatures.hh
 │    ├── CustomFeatures.cc
 │    ├── ...
-├── include/gz/physics/dartsim
 └── CMakeLists.txt
 ```

tutorials/09_use_custom_engine.md

@@ -158,13 +158,56 @@ While we won't go into detail, here is an example to test our new
 
 To get a more comprehensive view of how `EntityManagementFeatures` are constructed in TPE and Dartsim,
 feel free to take a look here:
-- Dartsim: [EntityManagementFeatures.hh](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/EntityManagementFeatures.hh) and [EntityManagementFeatures.cc](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/EntityManagementFeatures.cc)
-- TPE: [EntityManagementFeatures.hh](https://github.com/gazebosim/gz-physics/blob/ign-physics2/tpe/plugin/src/EntityManagementFeatures.hh) and [EntityManagementFeatures.cc](https://github.com/gazebosim/gz-physics/blob/ign-physics2/tpe/plugin/src/EntityManagementFeatures.cc)
+- Dartsim: [EntityManagementFeatures.hh](https://github.com/gazebosim/gz-physics/blob/main/dartsim/src/EntityManagementFeatures.hh) and [EntityManagementFeatures.cc](https://github.com/gazebosim/gz-physics/blob/main/dartsim/src/EntityManagementFeatures.cc)
+- TPE: [EntityManagementFeatures.hh](https://github.com/gazebosim/gz-physics/blob/main/tpe/plugin/src/EntityManagementFeatures.hh) and [EntityManagementFeatures.cc](https://github.com/gazebosim/gz-physics/blob/main/tpe/plugin/src/EntityManagementFeatures.cc)
+
+## Compile and run the example
+
+Clone the source code, create a build directory and use `cmake` to compile the code:
+
+```bash
+git clone https://github.com/gazebosim/gz-physics
+cd gz-physics/examples/simple_plugin
+mkdir build
+cd build
+cmake ..
+# Linux
+cmake --build . --target PluginTest
+# Windows
+cmake --build . --target PluginTest --config Release
+```
+
+Run the test to verify the new physis plugin:
+
+```bash
+# Linux
+./PluginTest
+
+# Windows
+.\Release\PluginTest.exe
+```
+
+You'll see:
+
+```bash
+$ ./PluginTest
+Created empty world!
+```
+
+Once you implement more features, you could try passing `SimplePlugin` as the physics engine
+to Gazebo Sim following \ref physicsengine "Use different physics engines" tutorial, e.g. setting
+
+    # Linux
+    export GZ_SIM_PHYSICS_ENGINE_PATH=$GZ_SIM_PHYSICS_ENGINE_PATH:$(pwd)/build
+    # Windows
+    set GZ_SIM_PHYSICS_ENGINE_PATH=<PATH_TO_THE_EXAMPLE_DIR>\build\Release
+
+And run Gazebo sim with
 
-## Load and test
+    gz sim -v4 -s --physics-engine SimplePlugin
 
-Please follow the previous tutorial \ref installation "Installation" to build
-`gz-physics` from source again for our new feature to be compiled.
+However, with the poor one feature we have implemented in this tutorial, you will only see an error,
+because Gazebo Sim needs much more features:
 
-Now we can load the new physics plugin named `gz-physics-tpe-plugin`
-to test it on Gazebo by following this \ref physicsengine "Use different physics engines" tutorial.
+    [error] [Physics.cc:854] No physics plugins implementing required interface found in library
+    [D:\programming\gz9-ws\gz-ws\src\gz-physics\examples\simple_plugin\build\Release\SimplePlugin.dll].