From 640f692c9d0662d507b01a105b2b4345b163f867 Mon Sep 17 00:00:00 2001 From: Jeongseok Lee Date: Fri, 14 Jun 2024 19:55:38 -0700 Subject: [PATCH] Update user guide pages (#3) Summary: Pull Request resolved: https://github.com/facebookincubator/momentum/pull/3 Reviewed By: yutingye Differential Revision: D58612312 --- .github/workflows/ci_macos.yml | 2 +- .github/workflows/ci_ubuntu.yml | 2 +- .github/workflows/ci_windows.yml | 6 +- README.md | 94 +++++-------- .../docs/02_user_guide/01_getting_started.md | 94 +++++-------- .../02_creating_your_applications.md | 127 ++++++++++++++++++ .../01_development_environment.md | 28 +--- pixi.toml | 3 + 8 files changed, 212 insertions(+), 144 deletions(-) create mode 100644 momentum/website/docs/02_user_guide/02_creating_your_applications.md diff --git a/.github/workflows/ci_macos.yml b/.github/workflows/ci_macos.yml index c18e3188..f0b0b4c5 100644 --- a/.github/workflows/ci_macos.yml +++ b/.github/workflows/ci_macos.yml @@ -34,7 +34,7 @@ jobs: pixi run test - name: Install Momentum and Build hello_world run: | - pixi run cmake --build build --target install --parallel + pixi run install pixi run cmake \ -S momentum/examples/hello_world \ -B momentum/examples/hello_world/build \ diff --git a/.github/workflows/ci_ubuntu.yml b/.github/workflows/ci_ubuntu.yml index 915b3471..621f39cb 100644 --- a/.github/workflows/ci_ubuntu.yml +++ b/.github/workflows/ci_ubuntu.yml @@ -28,7 +28,7 @@ jobs: pixi run test - name: Install Momentum and Build hello_world run: | - pixi run cmake --build build --target install --parallel + pixi run install pixi run cmake \ -S momentum/examples/hello_world \ -B momentum/examples/hello_world/build \ diff --git a/.github/workflows/ci_windows.yml b/.github/workflows/ci_windows.yml index 091b2563..12d66163 100644 --- a/.github/workflows/ci_windows.yml +++ b/.github/workflows/ci_windows.yml @@ -28,11 +28,7 @@ jobs: pixi run test - name: Install Momentum and Build hello_world run: | - pixi run cmake ` - --build build ` - --config Release ` - --target install ` - --parallel + pixi run install pixi run cmake ` -S momentum/examples/hello_world ` -B momentum/examples/hello_world/build diff --git a/README.md b/README.md index 3033e9f8..4082e7cf 100644 --- a/README.md +++ b/README.md @@ -11,101 +11,79 @@ numerical optimization solvers to apply human motion in various applications. ## Getting Started -### Supported Environments - -* **OS**: Windows, Linux, macOS +This page guides you through the process of building Momentum and running the examples. ### Prerequisite Complete the following steps only once: -- Install Pixi by following the instructions on https://prefix.dev/ - -### Install Momentum +1. Install Pixi by following the instructions on https://prefix.dev/ 1. Clone the repository and navigate to the root directory: - ``` - clone https://github.com/facebookincubator/momentum - cd momentum - ``` - -2. Build and install Momentum in a virtual environment using Pixi: - - ``` - pixi run cmake --build build --target install --parallel - ``` - -### Creating Your First Application + ``` + git clone https://github.com/facebookincubator/momentum + cd momentum + ``` -#### Writing Source Code + Ensure that all subsequent commands are executed in the project's root directory unless specified otherwise. -Now, let's define a simple Momentum application. Create a new file named `main.cpp` with the following content: +### Build Momentum -```cpp -#include +After completing the prerequisites, you are ready to build and use Momentum. -using namespace momentum; +- Build the project with the following command (note that the first run may take a few minutes as it installs all dependencies): -int main() { - auto mesh = Mesh(); - mesh.updateNormals(); - return EXIT_SUCCESS; -} -``` + ``` + pixi run build + ``` -#### Writing CMake Script +- Run the tests with: -Create a `CMakeLists.txt` file in the same directory as `main.cpp`. + ``` + pixi run test + ``` -To add momentum to your CMake project, first find the momentum package using the -`find_package` function and then add the appropriate `momentum::` as a -dependency to your library or executable. For example, if you want to use the -character functionality from momentum, you would add `momentum::character` as a -dependency: +To view all available command lines, run `pixi task list`. -```cmake -cmake_minimum_required(VERSION 3.16.3) +### Running Hello World -project(momentum) +To run the `hello_world` example: -find_package(momentum CONFIG REQUIRED) -add_executable(hello_world main.cpp) -target_link_libraries(hello_world PRIVATE momentum::math) +``` +pixi run hello-world ``` -Refer to the example project located at `momentum/examples/hello_world/` for the complete source code. - -#### Building using CMake - -To configure the application, run: +Alternatively, you can directly run the executable: ``` # Linux and macOS -pixi run cmake -S momentum/examples/hello_world -B momentum/examples/hello_world/build -DCMAKE_BUILD_TYPE=Release +./build/hello_world # Windows -pixi run cmake -S momentum/examples/hello_world -B momentum/examples/hello_world/build +./build/Release/hello_world.exe ``` -To build the application, run: +### Running Example -``` -# Linux and macOS -pixi run cmake --build momentum/examples/hello_world/build +To run other examples: -# Windows -pixi run cmake --build momentum/examples/hello_world/build --config Release +``` +pixi run glb-viewer --help ``` -#### Run the Application +For more examples, please refer to the [Examples](https://facebookincubator.github.io/momentum/docs/examples/viewers) page. -Execute the application with: +### Clean Up + +If you need to start over for any reason: ``` -./momentum/examples/hello_world/build/hello_world +pixi run clean ``` +Momentum uses the `build/` directory for CMake builds, `.pixi/` for the Pixi virtual environment, and `.deps/` for building dependencies. You can clean up everything by either manually removing these directories or by running the command above. + ## 📖 Documentation The full documentation for Momentum can be found on our [website][docs]. diff --git a/momentum/website/docs/02_user_guide/01_getting_started.md b/momentum/website/docs/02_user_guide/01_getting_started.md index dd5da983..17e2ef25 100644 --- a/momentum/website/docs/02_user_guide/01_getting_started.md +++ b/momentum/website/docs/02_user_guide/01_getting_started.md @@ -4,97 +4,75 @@ sidebar_position: 1 # Getting Started -## Supported Environments - -* **OS**: Windows, Linux, macOS +This page guides you through the process of building Momentum and running the examples. ## Prerequisite Complete the following steps only once: -- Install Pixi by following the instructions on https://prefix.dev/ - -## Install Momentum +1. Install Pixi by following the instructions on https://prefix.dev/ 1. Clone the repository and navigate to the root directory: - ``` - clone https://github.com/facebookincubator/momentum - cd momentum - ``` - -2. Build and install Momentum in a virtual environment using Pixi: - - ``` - pixi run cmake --build build --target install --parallel - ``` - -## Creating Your First Application + ``` + git clone https://github.com/facebookincubator/momentum + cd momentum + ``` -### Writing Source Code + Ensure that all subsequent commands are executed in the project's root directory unless specified otherwise. -Now, let's define a simple Momentum application. Create a new file named `main.cpp` with the following content: +## Build Momentum -```cpp -#include +After completing the prerequisites, you are ready to build and use Momentum. -using namespace momentum; +- Build the project with the following command (note that the first run may take a few minutes as it installs all dependencies): -int main() { - auto mesh = Mesh(); - mesh.updateNormals(); - return EXIT_SUCCESS; -} -``` + ``` + pixi run build + ``` -### Writing CMake Script +- Run the tests with: -Create a `CMakeLists.txt` file in the same directory as `main.cpp`. + ``` + pixi run test + ``` -To add momentum to your CMake project, first find the momentum package using the -`find_package` function and then add the appropriate `momentum::` as a -dependency to your library or executable. For example, if you want to use the -character functionality from momentum, you would add `momentum::character` as a -dependency: +To view all available command lines, run `pixi task list`. -```cmake -cmake_minimum_required(VERSION 3.16.3) +## Running Hello World -project(momentum) +To run the `hello_world` example: -find_package(momentum CONFIG REQUIRED) -add_executable(hello_world main.cpp) -target_link_libraries(hello_world PRIVATE momentum::math) +``` +pixi run hello-world ``` -Refer to the example project located at `momentum/examples/hello_world/` for the complete source code. - -### Building using CMake - -To configure the application, run: +Alternatively, you can directly run the executable: ``` # Linux and macOS -pixi run cmake -S momentum/examples/hello_world -B momentum/examples/hello_world/build -DCMAKE_BUILD_TYPE=Release +./build/hello_world # Windows -pixi run cmake -S momentum/examples/hello_world -B momentum/examples/hello_world/build +build/Release/hello_world.exe ``` -To build the application, run: +## Running Example -``` -# Linux and macOS -pixi run cmake --build momentum/examples/hello_world/build +To run other examples: -# Windows -pixi run cmake --build momentum/examples/hello_world/build --config Release +``` +pixi run glb-viewer --help ``` -### Run the Application +For more examples, please refer to the [Examples](../examples/viewers) page. -Execute the application with: +## Clean Up + +If you need to start over for any reason: ``` -./momentum/examples/hello_world/build/hello_world +pixi run clean ``` + +Momentum uses the `build/` directory for CMake builds, `.pixi/` for the Pixi virtual environment, and `.deps/` for building dependencies. You can clean up everything by either manually removing these directories or by running the command above. diff --git a/momentum/website/docs/02_user_guide/02_creating_your_applications.md b/momentum/website/docs/02_user_guide/02_creating_your_applications.md new file mode 100644 index 00000000..1c1de049 --- /dev/null +++ b/momentum/website/docs/02_user_guide/02_creating_your_applications.md @@ -0,0 +1,127 @@ +--- +sidebar_position: 2 +--- + +# Creating Your Applications + +This page guides you on how to create your own project that depends on the Momentum library. + +:::info + +We continue to use Pixi's virtual environment for building your project with Momentum and its dependencies. For alternative setups, please refer to the [Development Environment](../developer_guide/development_environment) page. + +::: + +## Install Momentum + +First, install Momentum in the virtual environment by running: + +``` +pixi run install +``` + +This command builds (in Release mode) and installs Momentum to `.pixi/envs/default/{include,lib,share}/` (Windows may have slightly different path). The necessary environment variables are set so that CMake can find Momentum (and other dependencies) using the environment variables in the virtual environment. + +## Writing Source Code + +Create a new file named `main.cpp` in your project root with the following content: + +```cpp +#include + +using namespace momentum; + +int main() { + auto mesh = Mesh(); + mesh.updateNormals(); + return EXIT_SUCCESS; +} +``` + +## Writing CMake Script + +Create a `CMakeLists.txt` file in the same directory as `main.cpp`. + +To add momentum to your CMake project, first find the momentum package using the +`find_package` function and then add the appropriate `momentum::` as a +dependency to your library or executable. For example, if you want to use the +character functionality from momentum, you would add `momentum::character` as a +dependency: + +```cmake +cmake_minimum_required(VERSION 3.16.3) + +project(momentum) + +find_package(momentum CONFIG REQUIRED) +add_executable(hello_world main.cpp) +target_link_libraries(hello_world PRIVATE momentum::math) +``` + +Refer to the example project located at `momentum/examples/hello_world/` for the complete source code. + +If you are developing a library that depends on Momentum: + +```cmake +add_library(my_lib SHARED my_lib.hpp my_lib.cpp) # shared +add_library(my_lib STATIC my_lib.hpp my_lib.cpp) # static +target_link_libraries(my_lib PUBLIC momentum::math) +``` + +## Building using CMake + +Assuming your project directory now contains: + +``` + + - CMakeLists.txt + - main.cpp +``` + +For convenience, we assume that your project root is located at `momentum/examples/hello_world/` because this code example is provided in that directory. You can use this working example as a reference, but feel free to adjust the path according to your actual project root. + +Here, we assume you are not using Pixi to build your project, but you are still within the Pixi environment for managing dependencies. + +To run any command in the virtual environment, use: + +``` +pixi run +``` + +Run the native CMake commands in the virtual environment as follows: + +To configure the application, run: + +``` +# Linux and macOS +pixi run cmake -S momentum/examples/hello_world -B momentum/examples/hello_world/build -DCMAKE_BUILD_TYPE=Release + +# Windows +pixi run cmake -S momentum/examples/hello_world -B momentum/examples/hello_world/build +``` + +To build the application, run: + +``` +# Linux and macOS +pixi run cmake --build momentum/examples/hello_world/build + +# Windows +pixi run cmake --build momentum/examples/hello_world/build --config Release +``` + +## Run the Application + +Execute the application with: + +``` +# Linux and macOS +./momentum/examples/hello_world/build/hello_world + +# Windows +momentum/examples/hello_world/build/Release/hello_world.exe +``` + +## Configuring Your Project with Pixi + +If you wish to use Pixi for your project similar to how it's implemented in Momentum, please visit [this website](https://pixi.sh/latest/basic_usage/) for detailed instructions. diff --git a/momentum/website/docs/04_developer_guide/01_development_environment.md b/momentum/website/docs/04_developer_guide/01_development_environment.md index 3eade010..837ba1ef 100644 --- a/momentum/website/docs/04_developer_guide/01_development_environment.md +++ b/momentum/website/docs/04_developer_guide/01_development_environment.md @@ -4,41 +4,27 @@ sidebar_position: 1 # Development Environment +## Supported Environments + +* **OS**: Windows, Linux, macOS + ## Package Manager Before developing Momentum, it is necessary to install various dependencies. This process can be platform-dependent and tedious. To simplify this, Momentum utilizes [Pixi](https://prefix.dev/). Pixi facilitates building Momentum in a virtual environment across different platforms (Windows, macOS ARM, Linux) using consistent command lines. -For those interested, you can examine the `pixi.toml`` file to see how dependencies are specified and to explore the available Pixi tasks for Momentum. +For those interested, you can examine the `pixi.toml` file to see how dependencies are specified and to explore the available Pixi tasks for Momentum. :::info -If you choose not to use Pixi, you will need to manually install all dependencies using platform-specific package managers. These typically install dependencies into the system directory. Ensure you have the appropriate package managers installed for your OS: [Homebrew](https://brew.sh/) for macOS, [Vcpkg](https://vcpkg.io/en/) for Windows, and apt for Ubuntu/Debian. After installation, refer to pixi.toml for guidance on what and how to install. +If you choose not to use Pixi, you will need to manually install all dependencies using platform-specific package managers. These typically install dependencies into the system directory. Ensure you have the appropriate package managers installed for your OS: [Homebrew](https://brew.sh/) for macOS, [Vcpkg](https://vcpkg.io/en/) for Windows, and apt for Ubuntu/Debian. After installation, refer to `pixi.toml` for guidance on what and how to install. ::: -## Running Predefined Tasks - -To build and manage the project using Pixi, follow these steps: - -- Build the project with the command: - - ``` - pixi run build - ``` - -- Run the tests using the command: - - ``` - pixi run test - ``` - -To view all available command lines, run `pixi task list`. - ## Running Custom Commands in Shell -To execute additional commands in the virtual environment, such as using CMake directly or running an executable, activate the virtual environment with: +To execute additional commands in the virtual environment other than the predefined tasks (to see the full tasks: `pixi task list`), such as using CMake directly or running an executable, activate the virtual environment with: ``` pixi shell diff --git a/pixi.toml b/pixi.toml index d04cff8a..5d5f5d19 100644 --- a/pixi.toml +++ b/pixi.toml @@ -261,3 +261,6 @@ glb-viewer = { cmd = "build/Release/glb_viewer.exe", depends_on = ["build"] } process-markers = { cmd = "build/Release/process_markers_app.exe", depends_on = [ "build", ] } +install = { cmd = "cmake --build build -j --target install --config Release", depends_on = [ + "build", +] }