From d71876301f13350e1db8fe9c12102aabb84e41e8 Mon Sep 17 00:00:00 2001 From: tyler-yankee Date: Fri, 17 Jan 2025 08:52:36 -0500 Subject: [PATCH 1/5] update docs for consistency in script calls, CMake build directories; remove deprecated reference to scripts/ directory in top-level README --- README.md | 2 +- drake_bazel_external/README.md | 2 +- drake_bazel_external_legacy/README.md | 2 +- drake_cmake_external/README.md | 2 +- drake_cmake_installed/README.md | 28 ++++++++++----------------- 5 files changed, 14 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 37b90d69..1be876d4 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ own project: ## Continuous Integration -Scripts are provided for various CI instances in `scripts/continuous_integration`. The intended purpose of each is described below: +Scripts are provided for various CI instances in each example's respective subdirectory under `.github/`. The intended purpose of each is described below: * `github_actions`: exemplifies how to put a project depending on a Drake installation on GitHub Actions * `jenkins` : provides complete coverage of additional external example projects diff --git a/drake_bazel_external/README.md b/drake_bazel_external/README.md index 7e605734..8dba803e 100644 --- a/drake_bazel_external/README.md +++ b/drake_bazel_external/README.md @@ -11,7 +11,7 @@ First, run the `install_prereqs` script to download the drake source and run drake's source setup script to install the required Ubuntu packages: ``` -setup/install_prereqs.sh +sudo setup/install_prereqs ``` Then, to build and test all apps: diff --git a/drake_bazel_external_legacy/README.md b/drake_bazel_external_legacy/README.md index a7f29fe0..76104a7f 100644 --- a/drake_bazel_external_legacy/README.md +++ b/drake_bazel_external_legacy/README.md @@ -16,7 +16,7 @@ First, run the `install_prereqs` script to download the drake source and run drake's source setup script to install the required Ubuntu packages: ``` -setup/install_prereqs.sh +sudo setup/install_prereqs ``` Then, to build and test all apps: diff --git a/drake_cmake_external/README.md b/drake_cmake_external/README.md index 63de8214..7eab8940 100644 --- a/drake_cmake_external/README.md +++ b/drake_cmake_external/README.md @@ -8,7 +8,7 @@ First, run the `install_prereqs` script to download the drake source and run drake's source setup script to install the required Ubuntu packages: ``` -setup/install_prereqs.sh +sudo setup/install_prereqs ``` Keep in mind that within the top-level CMakeLists, the drake source is once diff --git a/drake_cmake_installed/README.md b/drake_cmake_installed/README.md index b0cf7620..2c325626 100644 --- a/drake_cmake_installed/README.md +++ b/drake_cmake_installed/README.md @@ -13,14 +13,6 @@ These instructions are only supported for Ubuntu 22.04 (Jammy). # Various system dependencies sudo setup/install_prereqs -# (Optionally) Install GTest -# You could also explicitly pull gtest into the CMake build directly: -# https://github.com/google/googletest/tree/master/googletest -sudo apt-get install libgtest-dev -ls -mkdir ~/gtest && cd ~/gtest && cmake /usr/src/gtest && make -sudo cp *.a /usr/local/lib - ############################################################### # Install Drake to $HOME/drake ############################################################### @@ -34,20 +26,20 @@ tar -xvzf drake-latest-jammy.tar.gz -C $HOME # 3) Manual Installation # git clone https://github.com/RobotLocomotion/drake.git -# (mkdir drake-build && cd drake-build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake ../drake && make) +# (cd drake && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake .. && make) # 4) Manual Installation w/ Licensed Gurobi # Install & setup gurobi (http://drake.mit.edu/bazel.html?highlight=gurobi#install-on-ubuntu) # git clone https://github.com/RobotLocomotion/drake.git -# (mkdir drake-build && cd drake-build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake -DWITH_GUROBI=ON ../drake && make) +# (cd drake && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake -DWITH_GUROBI=ON .. && make) ############################################################### # Build Everything ############################################################### git clone https://github.com/RobotLocomotion/drake-external-examples.git -cd drake-external-examples -mkdir drake_cmake_installed-build && cd drake_cmake_installed-build -cmake -DCMAKE_PREFIX_PATH=$HOME/drake ../drake_cmake_installed +cd drake-external-examples/drake_cmake_installed +mkdir build && cd build +cmake -DCMAKE_PREFIX_PATH=$HOME/drake .. make # (Optionally) Run Tests make test @@ -73,8 +65,8 @@ build this project, and then run all available tests: ```shell # Build development version of Drake, ensuring no old artifacts are present. cd drake # Where you are developing. -rm -rf ../drake-build && mkdir ../drake-build && cd ../drake-build -cmake ../drake # Configure Gurobi, Mosek, etc, if needed. +rm -rf build && mkdir build && cd build +cmake .. # Configure Gurobi, Mosek, etc, if needed. # Build locally. make # Record the build's install directory. @@ -84,11 +76,11 @@ drake_install=${PWD}/install cd .. # Clone this repository if you have not already. git clone https://github.com/RobotLocomotion/drake-external-examples.git -cd drake-external-examples +cd drake-external-examples/drake_cmake_installed # Follow "Install Prerequisites" in the instructions linked above if you # have not already. -mkdir drake_cmake_installed-build && cd drake_cmake_installed-build -cmake -DCMAKE_PREFIX_PATH=${drake_install} ../drake_cmake_installed +mkdir build && cd build +cmake -DCMAKE_PREFIX_PATH=${drake_install} .. make ctest ``` From 73c8259afd662a7bc5dd6332985bac5ee07e38e6 Mon Sep 17 00:00:00 2001 From: tyler-yankee Date: Fri, 17 Jan 2025 14:00:27 -0500 Subject: [PATCH 2/5] fix shasum typo in drake_cmake_external CMake comment --- drake_cmake_external/CMakeLists.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/drake_cmake_external/CMakeLists.txt b/drake_cmake_external/CMakeLists.txt index 2244f821..a35d42a2 100644 --- a/drake_cmake_external/CMakeLists.txt +++ b/drake_cmake_external/CMakeLists.txt @@ -96,10 +96,10 @@ set(DRAKE_PREFIX "${PROJECT_BINARY_DIR}/drake-prefix") ExternalProject_Add(drake DEPENDS eigen fmt spdlog URL https://github.com/RobotLocomotion/drake/archive/master.tar.gz - # Or from a commit (download and use "shashum -a 256 'xxx.tar.gz'" on it to + # Or from a commit (download and use "shasum -a 256 'xxx.tar.gz'" on it to # get the URL_HASH. - # URL https://github.com/RobotLocomotion/drake/archive/65c4366ea2b63278a286b1e22b8d464d50fbe365.tar.gz - # URL_HASH SHA256=899d98485522a7cd5251e50a7a6b8a64e40aff2a3af4951a3f0857fd938cafca + # URL https://github.com/RobotLocomotion/drake/archive/962483669d015ee2618585ace2c884598fbadbb5.tar.gz + # URL_HASH SHA256=2605b7ba18ee7ab86e5a4f5ec6449766b0d4e9652bf5f701beb4f51bce251325 TLS_VERIFY ON CMAKE_ARGS -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE} From 72d4c8a0e6d0a73d9244c90a7133a602ee2ba64f Mon Sep 17 00:00:00 2001 From: tyler-yankee Date: Mon, 20 Jan 2025 10:38:38 -0500 Subject: [PATCH 3/5] [review] update READMEs for clarity; revert SHA change on CMakeLists --- README.md | 12 ++++++++---- drake_cmake_external/CMakeLists.txt | 4 ++-- drake_cmake_installed/README.md | 15 ++++++++++----- 3 files changed, 20 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 1be876d4..51454bf9 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,14 @@ own project: ## Continuous Integration -Scripts are provided for various CI instances in each example's respective subdirectory under `.github/`. The intended purpose of each is described below: - -* `github_actions`: exemplifies how to put a project depending on a Drake installation on GitHub Actions -* `jenkins` : provides complete coverage of additional external example projects +Scripts are provided for Jenkins or GitHub Actions, depending on the example, +in each example's respective subdirectory under `.github/`. +See the `Jenkinsfile` and the top-level `.github/workflows/ci.yml` +for a complete overview of each respective pipeline. +The intended purpose of each is described below: + +* GitHub Actions: exemplifies how to put a project depending on a Drake installation on GitHub Actions +* Jenkins: provides complete coverage of additional external example projects | **Subproject** | **GitHub Actions** | **Jenkins** | |:---:|:---:|:---:| diff --git a/drake_cmake_external/CMakeLists.txt b/drake_cmake_external/CMakeLists.txt index a35d42a2..ccbbe301 100644 --- a/drake_cmake_external/CMakeLists.txt +++ b/drake_cmake_external/CMakeLists.txt @@ -98,8 +98,8 @@ ExternalProject_Add(drake URL https://github.com/RobotLocomotion/drake/archive/master.tar.gz # Or from a commit (download and use "shasum -a 256 'xxx.tar.gz'" on it to # get the URL_HASH. - # URL https://github.com/RobotLocomotion/drake/archive/962483669d015ee2618585ace2c884598fbadbb5.tar.gz - # URL_HASH SHA256=2605b7ba18ee7ab86e5a4f5ec6449766b0d4e9652bf5f701beb4f51bce251325 + # URL https://github.com/RobotLocomotion/drake/archive/65c4366ea2b63278a286b1e22b8d464d50fbe365.tar.gz + # URL_HASH SHA256=899d98485522a7cd5251e50a7a6b8a64e40aff2a3af4951a3f0857fd938cafca TLS_VERIFY ON CMAKE_ARGS -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE} diff --git a/drake_cmake_installed/README.md b/drake_cmake_installed/README.md index 2c325626..1ee0215e 100644 --- a/drake_cmake_installed/README.md +++ b/drake_cmake_installed/README.md @@ -10,6 +10,7 @@ These instructions are only supported for Ubuntu 22.04 (Jammy). ############################################################### # Install Prerequisites ############################################################### + # Various system dependencies sudo setup/install_prereqs @@ -17,30 +18,34 @@ sudo setup/install_prereqs # Install Drake to $HOME/drake ############################################################### +# There are a few options to install drake: + # 1) A specific version (date-stamped) -# curl -O https://drake-packages.csail.mit.edu/drake/nightly/drake-20240214-jammy.tar.gz +curl -O https://drake-packages.csail.mit.edu/drake/nightly/drake-20240214-jammy.tar.gz # 2) The latest (usually last night's build) curl -O https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-jammy.tar.gz tar -xvzf drake-latest-jammy.tar.gz -C $HOME # 3) Manual Installation -# git clone https://github.com/RobotLocomotion/drake.git -# (cd drake && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake .. && make) +git clone https://github.com/RobotLocomotion/drake.git +(cd drake && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake .. && make) # 4) Manual Installation w/ Licensed Gurobi # Install & setup gurobi (http://drake.mit.edu/bazel.html?highlight=gurobi#install-on-ubuntu) -# git clone https://github.com/RobotLocomotion/drake.git -# (cd drake && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake -DWITH_GUROBI=ON .. && make) +git clone https://github.com/RobotLocomotion/drake.git +(cd drake && mkdir build && cd build && cmake -DCMAKE_INSTALL_PREFIX=$HOME/drake -DWITH_GUROBI=ON .. && make) ############################################################### # Build Everything ############################################################### + git clone https://github.com/RobotLocomotion/drake-external-examples.git cd drake-external-examples/drake_cmake_installed mkdir build && cd build cmake -DCMAKE_PREFIX_PATH=$HOME/drake .. make + # (Optionally) Run Tests make test ``` From ceadc70ab18c82302607ea20264fca5c3ece76de Mon Sep 17 00:00:00 2001 From: tyler-yankee Date: Tue, 21 Jan 2025 08:01:11 -0500 Subject: [PATCH 4/5] READMEs: remove trailing whitespace, use consistent spaces between code blocks, use bash syntax highlighting, update description in drake_bazel_download --- README.md | 8 ++++---- drake_bazel_download/README.md | 18 +++++++++++------- drake_bazel_external/README.md | 13 +++++++------ drake_bazel_external_legacy/README.md | 12 +++++++----- drake_cmake_external/README.md | 8 ++++---- drake_cmake_installed/README.md | 4 ++-- drake_cmake_installed_apt/README.md | 5 ++++- 7 files changed, 39 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 51454bf9..dd610ca1 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,10 @@ own project: ## Continuous Integration -Scripts are provided for Jenkins or GitHub Actions, depending on the example, -in each example's respective subdirectory under `.github/`. -See the `Jenkinsfile` and the top-level `.github/workflows/ci.yml` -for a complete overview of each respective pipeline. +Scripts are provided for Jenkins or GitHub Actions, depending on the example, +in each example's respective subdirectory under `.github/`. +See the `Jenkinsfile` and the top-level `.github/workflows/ci.yml` +for a complete overview of each respective pipeline. The intended purpose of each is described below: * GitHub Actions: exemplifies how to put a project depending on a Drake installation on GitHub Actions diff --git a/drake_bazel_download/README.md b/drake_bazel_download/README.md index 7409a25c..562c335a 100644 --- a/drake_bazel_download/README.md +++ b/drake_bazel_download/README.md @@ -8,29 +8,33 @@ For an introduction to Bazel, refer to ## Instructions -First, install the required Ubuntu packages: +First, run the `install_prereqs` script to download the Drake source and run +its setup script to install the required Ubuntu packages: -``` +```bash sudo setup/install_prereqs ``` -If you don't already have bazel or bazelisk installed, then install bazelisk: -``` +Additionally, if you don't already have bazel or bazelisk installed, then install bazelisk: + +```bash sudo setup/install_bazelisk ``` Then, to build and test all apps: -``` + +```bash bazel test //... ``` As an example to run a binary directly: -``` + +```bash bazel run //apps:simple_logging_example ``` You may also run the binary directly per the `bazel-bin/...` path that the above command prints out; however, be aware that your working directories may -cause differences. This is important when using tools like +cause differences. This is important when using tools like `drake::FindResource` / `pydrake.common.FindResource`. You may generally want to stick to using `bazel run` when able. diff --git a/drake_bazel_external/README.md b/drake_bazel_external/README.md index 8dba803e..86fef6be 100644 --- a/drake_bazel_external/README.md +++ b/drake_bazel_external/README.md @@ -7,20 +7,20 @@ For an introduction to Bazel, refer to ## Instructions -First, run the `install_prereqs` script to download the drake source and run -drake's source setup script to install the required Ubuntu packages: +First, run the `install_prereqs` script to download the Drake source and run +its setup script to install the required Ubuntu packages: -``` +```bash sudo setup/install_prereqs ``` Then, to build and test all apps: -``` +```bash bazel test //... ``` As an example to run a binary directly: -``` +```bash bazel run //apps:simple_logging_example ``` @@ -35,7 +35,8 @@ You may generally want to stick to using `bazel run` when able. To use Drake sources on disk instead of downloaded from github, pass the flag ``--override_module=drake=/home/user/stuff/drake`` to bazel on the command line or add a line such as the following to ``user.bazelrc`` in the current directory: -``` + +```bash build --override_module=drake=/home/user/stuff/drake ``` diff --git a/drake_bazel_external_legacy/README.md b/drake_bazel_external_legacy/README.md index 76104a7f..ef170163 100644 --- a/drake_bazel_external_legacy/README.md +++ b/drake_bazel_external_legacy/README.md @@ -12,20 +12,22 @@ For an introduction to Bazel, refer to ## Instructions -First, run the `install_prereqs` script to download the drake source and run -drake's source setup script to install the required Ubuntu packages: +First, run the `install_prereqs` script to download the Drake source and run +its setup script to install the required Ubuntu packages: -``` +```bash sudo setup/install_prereqs ``` Then, to build and test all apps: -``` + +```bash bazel test //... ``` As an example to run a binary directly: -``` + +```bash bazel run //apps:simple_logging_example ``` diff --git a/drake_cmake_external/README.md b/drake_cmake_external/README.md index 7eab8940..c7b4dcd4 100644 --- a/drake_cmake_external/README.md +++ b/drake_cmake_external/README.md @@ -4,10 +4,10 @@ This pulls in Drake using the CMake `ExternalProject_Add(drake)` mechanism. ## Instructions -First, run the `install_prereqs` script to download the drake source and run -drake's source setup script to install the required Ubuntu packages: +First, run the `install_prereqs` script to download the Drake source and run +its setup script to install the required Ubuntu packages: -``` +```bash sudo setup/install_prereqs ``` @@ -19,7 +19,7 @@ changed within that version, then the script ran above must also be modified. Once all necessary dependencies have been installed, build and run tests using CMake: -``` +```bash mkdir build cd build cmake .. diff --git a/drake_cmake_installed/README.md b/drake_cmake_installed/README.md index 1ee0215e..4905fd06 100644 --- a/drake_cmake_installed/README.md +++ b/drake_cmake_installed/README.md @@ -6,7 +6,7 @@ This uses the CMake `find_package(drake)` mechanism to find an installed instanc These instructions are only supported for Ubuntu 22.04 (Jammy). -```shell +```bash ############################################################### # Install Prerequisites ############################################################### @@ -67,7 +67,7 @@ These build instructions are adapted from those above, but will use an existing source tree of Drake (but *not* installing it to `$HOME/drake`), build this project, and then run all available tests: -```shell +```bash # Build development version of Drake, ensuring no old artifacts are present. cd drake # Where you are developing. rm -rf build && mkdir build && cd build diff --git a/drake_cmake_installed_apt/README.md b/drake_cmake_installed_apt/README.md index 57350a00..61f30bc5 100644 --- a/drake_cmake_installed_apt/README.md +++ b/drake_cmake_installed_apt/README.md @@ -12,12 +12,14 @@ Install the `drake-dev` APT package by following the instructions found at: For this example, also install the `build-essential` and `cmake` APT packages: + ```bash sudo apt-get update -sudo apt-get --no-install-recommends install build-essential cmake +sudo apt-get --no-install-recommends install build-essential cmake ``` To build the `drake_cmake_installed_apt` example: + ```bash mkdir build cd build @@ -26,6 +28,7 @@ make ``` To run the `drake_cmake_installed_apt` tests: + ```bash cd build ctest . From 24594a28bb60bd0c2bc1d4523269cca46c35981d Mon Sep 17 00:00:00 2001 From: tyler-yankee Date: Tue, 21 Jan 2025 08:15:55 -0500 Subject: [PATCH 5/5] add clarity for where drake is being downloaded or installed for each example --- drake_bazel_download/README.md | 4 ++-- drake_bazel_external/README.md | 7 +++++-- drake_bazel_external_legacy/README.md | 5 +++-- drake_cmake_external/README.md | 5 +++-- drake_cmake_installed/README.md | 5 +++-- 5 files changed, 16 insertions(+), 10 deletions(-) diff --git a/drake_bazel_download/README.md b/drake_bazel_download/README.md index 562c335a..eca70de5 100644 --- a/drake_bazel_download/README.md +++ b/drake_bazel_download/README.md @@ -8,8 +8,8 @@ For an introduction to Bazel, refer to ## Instructions -First, run the `install_prereqs` script to download the Drake source and run -its setup script to install the required Ubuntu packages: +First, run the `install_prereqs` script to download the Drake source to `/opt/drake/`. +This also runs Drake's setup script to install the required Ubuntu packages: ```bash sudo setup/install_prereqs diff --git a/drake_bazel_external/README.md b/drake_bazel_external/README.md index 86fef6be..37b3f03e 100644 --- a/drake_bazel_external/README.md +++ b/drake_bazel_external/README.md @@ -7,19 +7,22 @@ For an introduction to Bazel, refer to ## Instructions -First, run the `install_prereqs` script to download the Drake source and run -its setup script to install the required Ubuntu packages: +First, run the `install_prereqs` script to download the Drake source to `drake-master/` +(from the current directory). This also runs Drake's setup script to +install the required Ubuntu packages: ```bash sudo setup/install_prereqs ``` Then, to build and test all apps: + ```bash bazel test //... ``` As an example to run a binary directly: + ```bash bazel run //apps:simple_logging_example ``` diff --git a/drake_bazel_external_legacy/README.md b/drake_bazel_external_legacy/README.md index ef170163..99acca4d 100644 --- a/drake_bazel_external_legacy/README.md +++ b/drake_bazel_external_legacy/README.md @@ -12,8 +12,9 @@ For an introduction to Bazel, refer to ## Instructions -First, run the `install_prereqs` script to download the Drake source and run -its setup script to install the required Ubuntu packages: +First, run the `install_prereqs` script to download the Drake source to `drake-master/` +(from the current directory). This also runs Drake's setup script to +install the required Ubuntu packages: ```bash sudo setup/install_prereqs diff --git a/drake_cmake_external/README.md b/drake_cmake_external/README.md index c7b4dcd4..55171280 100644 --- a/drake_cmake_external/README.md +++ b/drake_cmake_external/README.md @@ -4,8 +4,9 @@ This pulls in Drake using the CMake `ExternalProject_Add(drake)` mechanism. ## Instructions -First, run the `install_prereqs` script to download the Drake source and run -its setup script to install the required Ubuntu packages: +First, run the `install_prereqs` script to download the Drake source to `drake-master/` +(from the current directory). This also runs Drake's setup script to +install the required Ubuntu packages: ```bash sudo setup/install_prereqs diff --git a/drake_cmake_installed/README.md b/drake_cmake_installed/README.md index 4905fd06..54e65b8a 100644 --- a/drake_cmake_installed/README.md +++ b/drake_cmake_installed/README.md @@ -11,7 +11,8 @@ These instructions are only supported for Ubuntu 22.04 (Jammy). # Install Prerequisites ############################################################### -# Various system dependencies +# Download Drake source to /opt/drake/ and install +# various system dependencies sudo setup/install_prereqs ############################################################### @@ -52,7 +53,7 @@ make test # Examples -Drake specific Examples: +Drake-specific examples: * [Simple Continuous Time System](src/simple_continuous_time_system/README.md) * [Particle System](src/particle)