Reorganize utiltiy scripts for building and installing 3rd-party depe…

…ndencies:

- organize in subdirectories by operating system
- add scripts for installing Eigen3, Blaze, and Spectra
- add description Readme file

README.md

@@ -1,13 +1,3 @@
-ATTENTION
-=========
-
-The structure of the Chrono git repository was changed as follows:
-
-- The main development branch is now called `main` (previously `develop`)
-- The `master` branch, now obsolete, was deleted
-- Releases are located in branches named `release/*.*` and have tags of the form `*.*.*`
-
-
 Project CHRONO
 ==============
 
@@ -48,3 +38,10 @@ Implemented almost entirely in C++, Chrono also provides Python and C# APIs. The
 ### Support
 
 - [Google Groups user forum](https://groups.google.com/g/projectchrono)
+
+### Note on Chrono repository structure
+
+The structure of the Chrono git repository was changed as follows:
+- The main development branch is now called `main` (previously `develop`)
+- The `master` branch, now obsolete, was deleted
+- Releases are located in branches named `release/*.*` and have tags of the form `*.*.*`

contrib/build-scripts/README.md

@@ -0,0 +1,39 @@
+Utility scripts for configuring, building, and installing Chrono 3rd-party dependencies
+==============
+
+The scripts in this directory provide a simple mechanism for installing dependencies for the various Chrono modules.  The scripts are organized iun sub-directories by OS: Bash shell scripts in `linux/` and Windows batch scripts in `windows/`. The directory `macOS/` contains Bash shell scripts tailored for the specifics of MacOS. If a script is not present in that directory, simply use the generic one in `linux/`.
+
+Notes
+- the scripts assume that git, cmake, and a C++ compiler are available
+- additional requirements (if any) are indicated in the comments at the top of each script
+- usage instrauctions are listed in the comments at the top of each script
+
+Currently, scripts are provided for the following packages:
+- Eigen3 -- the only external dependency of the core Chrono module
+- Blaze -- a linear algebra package required by Chrono::Multicore
+- GL and GLEW -- OpenGL packages used in Chrono::OpenGL and (optionally) in Chrono::Sensor
+- MUMPS -- a direct sparse linear solver required by Chrono::Mumps
+- OpenCRG -- a file format for road description used (optionally) in Chrono::Vehicle
+- Spectra -- an algebra package required by Chrono::Modal
+- URDF -- URDF file parser utilities optionally used by Chrono::Parsers
+- VDB -- OpenVDB packages optionally used in Chrono::Sensor
+- VSG -- VulkanSceneGraph packages required by Chrono::VSG
+
+In addition, each sub-directory includes a sample script for configuring and building Chrono with vrious modules enabled and satisfying the corresponding dependencies.
+
+## Usage
+
+Consult the instructions in the comments at the top of each script.
+The general usage is as follows:
+- copy the desired script(s) in a workspace directory (each script will create temporary directories to download the necessary sources and to configure and build the various packages)
+- edit the script to tailor to your particular machine (at a minimum, set the desired installation directory)
+- run the script
+- verify that the package files were properly installed in the specified install directory
+
+With the exception of OpenCRG, all packages built and installed by these scripts provide CMake configuration scripts which are used during CMake Chrono configuration to find the respective dependencies. To simplify the Chrono CMake configuration process and avoid manually specifying package-specific information every time, we recommend setting the `CMNAKE_PREFIX_PATH` environment variable to add the directory containing the CMake project configuration scripts for each installed package. 
+An example of `CMAKE_PREFIX_PATH` (on a Windows machine) is:
+`E:\Packages\eigen\share\eigen3\cmake;E:\Packages\blaze\share\blaze\cmake;E:\Packages\vsg\lib\cmake;E:\Packages\urdf\lib\urdfdom\cmake;E:\Packages\urdf\CMake;E:\Packages\spectra\share\spectra\cmake;E:\Packages\gl\lib\cmake;E:\Packages\mumps\cmake;C:\OpenCASCADE-7.4.0-vc14-64\opencascade-7.4.0\cmake;C:\Program Files (x86)\Intel\oneAPI\mkl\2023.0.0\lib\cmake\mkl;`
+
+Since many of these packages create and install shared libraries, the following steps may be required:
+- on Linux, run `ldconfig` (you will likely need root permissions) to cache the necessary link to the newly created shared libraries or set the `LD_LIBRARY_PATH` environment variable
+- on Windows, add to the `PATH` environment variable the directories containing the package DLLs (otherwise, these DLLs have to be manually copied next to the binaries so that they can be found at run-time)

contrib/build-scripts/linux/buildBlaze.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+# -------------------------------------------------------------------------------------------------------
+# Shell script for building and installing Blaze.
+# - Requires git, cmake, and ninja.
+# - Place in an arbitrary temporary directory.
+# - Specify the install directory.
+# - Run the script (sh ./buildBlaze.sh).
+# - The install directory will contain subdirectories for all necessary dependencies.
+#
+# Notes:
+# - The script accepts 1 optional argument to override the install directory.
+# - If ninja is not available, set BUILD_SYSTEM="Unix Makefiles" or some other generator
+# -------------------------------------------------------------------------------------------------------
+
+BLAZE_INSTALL_DIR="$HOME/Packages/blaze"
+
+BUILD_SYSTEM="Ninja"
+
+# Allow overriding installation directory through command line argument
+if [ $# -eq 1 ]
+then
+    BLAZE_INSTALL_DIR=$1
+fi
+
+echo "----------------------------- Download sources from Bitbucket"
+
+rm -rf download_blaze
+mkdir download_blaze
+
+git clone -c advice.detachedHead=false --depth 1 --branch v3.8.2 "https://bitbucket.org/blaze-lib/blaze.git" "download_blaze"
+
+rm -rf ${BLAZE_INSTALL_DIR}
+mkdir ${BLAZE_INSTALL_DIR}
+
+echo -e "\n------------------------ Configure Blaze\n"
+rm -rf build_blaze
+cmake -G "${BUILD_SYSTEM}" -B build_blaze -S download_blaze
+
+echo -e "\n------------------------ Build and install Blaze\n"
+# cmake --build build_blaze --config Release
+cmake --install build_blaze --config Release --prefix ${BLAZE_INSTALL_DIR}

contrib/build-scripts/linux/buildEigen.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+# -------------------------------------------------------------------------------------------------------
+# Shell script for building and installing Eigen3.
+# - Requires git, cmake, and ninja.
+# - Place in an arbitrary temporary directory.
+# - Specify the install directory.
+# - Run the script (sh ./buildEigen.sh).
+# - The install directory will contain subdirectories for all necessary dependencies.
+#
+# Notes:
+# - The script accepts 1 optional argument to override the install directory.
+# - If ninja is not available, set BUILD_SYSTEM="Unix Makefiles" or some other generator
+# -------------------------------------------------------------------------------------------------------
+
+EIGEN_INSTALL_DIR="$HOME/Packages/eigen"
+
+BUILD_SYSTEM="Ninja"
+
+# Allow overriding installation directory through command line argument
+if [ $# -eq 1 ]
+then
+    EIGEN_INSTALL_DIR=$1
+fi
+
+echo "----------------------------- Download sources from GitLab"
+
+rm -rf download_eigen
+mkdir download_eigen
+
+git clone -c advice.detachedHead=false --depth 1 --branch 3.4.0 "https://gitlab.com/libeigen/eigen.git" "download_eigen"
+
+rm -rf ${EIGEN_INSTALL_DIR}
+mkdir ${EIGEN_INSTALL_DIR}
+
+echo -e "\n------------------------ Configure Eigen\n"
+rm -rf build_eigen
+cmake -G "${BUILD_SYSTEM}" -B build_eigen -S download_eigen
+
+echo -e "\n------------------------ Build and install Eigen\n"
+# cmake --build build_eigen --config Release
+cmake --install build_eigen --config Release --prefix ${EIGEN_INSTALL_DIR}

contrib/build-scripts/opengl/buildGL.sh → contrib/build-scripts/linux/buildGL.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # ---------------------------------------------------------------------------------------------------------
-# Windows batch script for building GL from sources.
+# Shell script for building GL from sources.
 # - Requires cmake, wget, and unzip
 # - Place in an arbitrary temporary directory.
 # - Specify the locations for the GL sources OR indicate that these should be downloaded.

contrib/build-scripts/opengl/buildGLEW.sh → contrib/build-scripts/linux/buildGLEW.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # ---------------------------------------------------------------------------------------------------------
-# Windows batch script for building GLEW from source.
+# Shell batch script for building GLEW from source.
 # - Requires cmake, wget, and unzip
 # - Place in an arbitrary temporary directory.
 # - Specify the locations for the GLEW source OR indicate that it should be downloaded.

contrib/build-scripts/mumps/buildMUMPS.sh → contrib/build-scripts/linux/buildMUMPS.sh

@@ -24,7 +24,7 @@
 #   Modify the CMake configuration below to enable other options (e.g., alternative ordering algorithms).
 # -------------------------------------------------------------------------------------------------------
 
-MUMPS_INSTALL_DIR="/usr/local/mumps"
+MUMPS_INSTALL_DIR="$HOME/Packages/mumps"
 
 # Build MUMPS debug libraries
 BUILD_DEBUG=ON
@@ -45,6 +45,9 @@ mkdir download_mumps
 # Note: use custom fork of scivision/mumps
 git clone "https://github.com/projectchrono/mumps.git" download_mumps
 
+rm -rf ${MUMPS_INSTALL_DIR}
+mkdir ${MUMPS_INSTALL_DIR}
+
 echo -e "\n------------------------ Configure mumps\n"
 rm -rf build_mumps
 cmake -G "${BUILD_SYSTEM}" -B build_mumps -S download_mumps \
@@ -58,11 +61,11 @@ cmake -G "${BUILD_SYSTEM}" -B build_mumps -S download_mumps \
 
 echo -e "\n------------------------ Build and install mumps\n"
 cmake --build build_mumps --config Release
-sudo cmake --install build_mumps --config Release --prefix ${MUMPS_INSTALL_DIR}
+cmake --install build_mumps --config Release --prefix ${MUMPS_INSTALL_DIR}
 if [ ${BUILD_DEBUG} = ON ]
 then
     cmake --build build_mumps --config Debug
-    sudo cmake --install build_mumps --config Debug --prefix ${MUMPS_INSTALL_DIR}
+    cmake --install build_mumps --config Debug --prefix ${MUMPS_INSTALL_DIR}
 else
     echo "No Debug build of mumps"
 fi

contrib/build-scripts/linux/buildSpectra.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# -------------------------------------------------------------------------------------------------------
+# Shell script for building and installing Spectra.
+# - Requires git, cmake, and ninja.
+# - Place in an arbitrary temporary directory.
+# - Specify the install directory.
+# - Run the script (sh ./buildSpectra.sh).
+# - The install directory will contain subdirectories for all necessary dependencies.
+#
+# Notes:
+# - Chrono uses the Krylov-Schur solver from Spectra, available *only* in the Spectra development branch.
+# - The script accepts 1 optional argument to override the install directory.
+# - If ninja is not available, set BUILD_SYSTEM="Unix Makefiles" or some other generator
+# -------------------------------------------------------------------------------------------------------
+
+SPECTRA_INSTALL_DIR="$HOME/Packages/spectra"
+
+BUILD_SYSTEM="Ninja"
+
+# Allow overriding installation directory through command line argument
+if [ $# -eq 1 ]
+then
+    SPECTRA_INSTALL_DIR=$1
+fi
+
+echo "----------------------------- Download sources from GitHub"
+
+rm -rf download_spectra
+mkdir download_spectra
+
+git clone -c advice.detachedHead=false --depth 1 --branch develop "https://github.com/yixuan/spectra.git" "download_spectra"
+
+rm -rf ${SPECTRA_INSTALL_DIR}
+mkdir ${SPECTRA_INSTALL_DIR}
+
+echo -e "\n------------------------ Configure Spectra\n"
+rm -rf build_spectra
+cmake -G "${BUILD_SYSTEM}" -B build_spectra -S download_spectra
+
+echo -e "\n------------------------ Build and install Spectra\n"
+# cmake --build build_spectra --config Release
+cmake --install build_spectra --config Release --prefix ${SPECTRA_INSTALL_DIR}

contrib/build-scripts/windows/buildBlaze.bat

@@ -0,0 +1,52 @@
+@rem ---------------------------------------------------------------------------------------------------------
+@rem Windows batch script for building and installing Blaze
+@rem - Place in an arbitrary temporary directory.
+@rem - Specify the locations for the Blaze source OR indicate that it should be downloaded.
+@rem - Specify the install directory.
+@rem - Run the script (.\buildBlaze.bat).
+@rem - The install directory will contain subdirectories for all necessary dependencies.
+@rem
+@rem Notes:
+@rem - The script accepts 1 optional argument to override the install directory.
+@rem ---------------------------------------------------------------------------------------------------------
+
+set DOWNLOAD=ON
+
+set BLAZE_INSTALL_DIR="C:/Packages/blaze"
+
+@if %DOWNLOAD% EQU OFF (
+    set BLAZE_SOURCE_DIR="C:/Sources/blaze"
+)
+
+@rem ------------------------------------------------------------------------
+@rem Allow overriding installation directory through command line argument
+
+if "%~1" NEQ "" (
+   set BLAZE_INSTALL_DIR=%1
+)
+
+@rem ------------------------------------------------------------------------
+
+@if %DOWNLOAD% EQU ON (
+    echo "Downloading source from Bitbucket"
+
+    rmdir /S/Q download_blaze 2>nul
+    mkdir download_blaze
+
+    git clone -c advice.detachedHead=false --depth 1 --branch v3.8.2 "https://bitbucket.org/blaze-lib/blaze.git" "download_blaze"
+    set BLAZE_SOURCE_DIR="download_blaze"
+) else (
+    echo "Using provided source directories"
+)
+
+@rem ------------------------------------------------------------------------
+
+rmdir /S/Q %BLAZE_INSTALL_DIR% 2>nul
+
+rmdir /S/Q build_blaze 2>nul
+cmake -B build_blaze -S %BLAZE_SOURCE_DIR%
+
+@rem cmake --build build_blaze --config Release
+cmake --install build_blaze --config Release --prefix %BLAZE_INSTALL_DIR%
+
+

contrib/build-scripts/windows/buildEigen.bat

@@ -0,0 +1,52 @@
+@rem ---------------------------------------------------------------------------------------------------------
+@rem Windows batch script for building and installing Eigen3.
+@rem - Place in an arbitrary temporary directory.
+@rem - Specify the locations for the Eigen source OR indicate that it should be downloaded.
+@rem - Specify the install directory.
+@rem - Run the script (.\buildEigen.bat).
+@rem - The install directory will contain subdirectories for all necessary dependencies.
+@rem
+@rem Notes:
+@rem - The script accepts 1 optional argument to override the install directory.
+@rem ---------------------------------------------------------------------------------------------------------
+
+set DOWNLOAD=ON
+
+set EIGEN_INSTALL_DIR="C:/Packages/eigen"
+
+@if %DOWNLOAD% EQU OFF (
+    set EIGEN_SOURCE_DIR="C:/Sources/eigen"
+)
+
+@rem ------------------------------------------------------------------------
+@rem Allow overriding installation directory through command line argument
+
+if "%~1" NEQ "" (
+   set EIGEN_INSTALL_DIR=%1
+)
+
+@rem ------------------------------------------------------------------------
+
+@if %DOWNLOAD% EQU ON (
+    echo "Downloading source from GitLab"
+
+    rmdir /S/Q download_eigen 2>nul
+    mkdir download_eigen
+
+    git clone -c advice.detachedHead=false --depth 1 --branch 3.4.0 "https://gitlab.com/libeigen/eigen.git" "download_eigen"
+    set EIGEN_SOURCE_DIR="download_eigen"
+) else (
+    echo "Using provided source directories"
+)
+
+@rem ------------------------------------------------------------------------
+
+rmdir /S/Q %EIGEN_INSTALL_DIR% 2>nul
+
+rmdir /S/Q build_eigen 2>nul
+cmake -B build_eigen -S %EIGEN_SOURCE_DIR%
+
+@rem cmake --build build_eigen --config Release
+cmake --install build_eigen --config Release --prefix %EIGEN_INSTALL_DIR%
+
+