From f4bab02f9f43b1449bd4e26b717812077644e253 Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Fri, 15 Sep 2023 11:57:06 -0600 Subject: [PATCH 1/6] update documentation to discuss how to check in a virtual environment if the expected versions of python are being called. --- docs/source/Install/customPython.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/source/Install/customPython.rst b/docs/source/Install/customPython.rst index 8de25d2a53..7313d50b7a 100644 --- a/docs/source/Install/customPython.rst +++ b/docs/source/Install/customPython.rst @@ -18,4 +18,8 @@ computer that is not using a system installed version of Python. a virtual python environment, such as with ``venv``. In this case only that python used to create the virtual environment is available and conflicts with other versions are avoided. - If you use a virtual environment, but sure to build Basilisk in that virtual environment for the simulation - script to function. + script to function. For example, within the virtual environment type ``python --version`` to check + that the correct version of python is called with the ``python`` command. On Linux and macOS, you can + also check what python version the ``python3`` command uses. Alternatively, calling + ``where python`` will show you what python option there are, and what version will be called by + looking for the top entry. From 3de6004dfb6cf67329004d896cfb0eff67b2880c Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Wed, 20 Sep 2023 07:24:50 +0100 Subject: [PATCH 2/6] separate out the build process documentation that employs conan and cmake directly. --- docs/source/Install.rst | 1 + docs/source/Install/installBuild.rst | 185 ++------------------- docs/source/Install/installBuildConan.rst | 191 ++++++++++++++++++++++ 3 files changed, 205 insertions(+), 172 deletions(-) create mode 100644 docs/source/Install/installBuildConan.rst diff --git a/docs/source/Install.rst b/docs/source/Install.rst index 13c9197d18..7ce0fa128b 100644 --- a/docs/source/Install.rst +++ b/docs/source/Install.rst @@ -20,6 +20,7 @@ Install Install/buildExtModules Install/installOptionalPackages Install/customPython + Install/installBuildConan diff --git a/docs/source/Install/installBuild.rst b/docs/source/Install/installBuild.rst index 05f0843f42..f02abf454c 100644 --- a/docs/source/Install/installBuild.rst +++ b/docs/source/Install/installBuild.rst @@ -111,179 +111,20 @@ The ``buildProject`` argument here is optional as its default value is ``True``. example, if you do a regular build you are building for debug, not for release. Thus, be mindful of how you are building the code. -Configuring and Building with ``conan`` Commands ------------------------------------------------- -Calling ``conanfile.py`` with python executes a method that calls two separate ``conan`` function to setup and -configure process, and build the executable if desired. This section outlines this 2-step build process for -those that seek to build it this way. +Doing Incremental Builds +------------------------ +If you are developing new Basilisk capabilities you will be looking to do incremental builds. Note that running +``python conanfile.py`` will delete the auto-created messaging related files and their compiled products. +Compiling the messaging related files is a large component of the Basilisk build time. Thus, running +this command is required if you make changes to the message file definitions, or add a new message file. However, +it is not the preferred manner to compile Basilisk if you just need to do an incremental build. + +Rather, run ``python conanfile.py --buildProject False`` to create the IDE file for your platform +such as Xcode projeect file on macOS, MS Visual Studio project file on Windows, etc. Next, +open the project file in your IDE and compile Basilisk there. The initial build is a clean build and will take a +similar amount of time to compile the messaging related files. However, after making changes to a particular module, +only this Basilisk module will need to be compiled and the compile times are drastically reduced. -.. note:: - - All commands are called from the Basilisk root directory. - -Step 1: Installing Basilisk Dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The first command, in its minimalist form, is:: - - conan install . -if dist3/conan --build=missing - -This conan command will create the distribution folder, ``dist3`` in the above case, if needed, collect all the -require Basilisk 3rd party resources and compile them if their binaries are missing. The cmake files to access these -3rd party libraries are stored in ``dist3/conan``. - -There are several options that can be provided to this ``conan install`` command as shown in the following table. -Note that the option names for groupings of Basilisk modules are the same as with the one-step build above. - -.. list-table:: Options for ``conan install`` Step - :widths: 15 15 10 60 - :header-rows: 1 - - * - Option - - Values - - Default - - Description - * - ``-o vizInterface`` - - Boolean - - True - - Include :ref:`vizInterface` in the configuration and build - * - ``-o opNav`` - - Boolean - - False - - Include the `OpenCV `__ library dependent Basilisk modules. - * - ``-o clean`` - - Boolean - - False - - Delete the distribution folder before configuring to yield a fresh build - * - ``-o buildProject`` - - Boolean - - True - - Will build the project executable after the configuration step - * - ``-s build_type`` - - Release, Debug - - Release - - Specifies the build type - * - ``-o generator`` - - see `here `__ - - ``XCode`` (macOS), ``Visual Studio 16 2019`` (Windows), ``None`` (Linux) - - Used to specify a specific ``cmake`` generator. See discussion in Table :ref:`buildTable1Label`. - * - ``-o autoKey`` - - String 's' or 'u' - - Empty - - This is used to automatically respond to the python packaging installation requests to install the - package for the user (u) or system (s). - * - ``-o allOptPkg`` - - Boolean - - False - - Install all of the optional Basilisk python package dependencies - -Thus, using the same build example as in the one-step section, to create a build with ``opNav`` modes enabled, -but no :ref:`vizInterface`, and using a clean distribution folder, and that is built right away, you could use:: - - conan install . -if dist3/conan --build=missing -o clean=True -o buildProject=True -o opNav=True -o vizInterface=False - -Note how much more verbose this is, but it gives you full control if you want to store the compiled binaries and -cmake files in directories other than ``dist3/conan``. - -Step 2: Creating the IDE Project -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The final step is to create the IDE project file and possibly build the executables directly. -At this stage there are no options to be provided. This step is done with:: - - conan build . -if dist3/conan - -.. warning:: - - If you want the ``conan build`` command to automatically compile the code, the ``buildProject`` option - must be set in the ``conan install`` step. - - -Running ``cmake`` Directly --------------------------- - -The ``conan install`` command must always be run to install the required dependencies and compile them. If the -developer wishes, the ``cmake`` can be run directly from the ``dist3`` distribution folder instead -of relying on the ``conan build`` step discussed above. - -The following table summarizes the optional Basilisk related flags that can be provided to ``cmake``. If -they are not used, then the shown default behaviors are used. - -.. list-table:: ``cmake`` Basilisk Build Flags - :widths: 25 15 70 - :header-rows: 1 - - * - cmake Flag - - Default - - Description - * - ``BUILD_VIZINTERFACE`` - - ``ON`` - - will create :ref:`vizInterface` - * - ``BUILD_OPNAV`` - - ``OFF`` - - will create the OpenCL dependent optical navigation related modules - -macOS Example -~~~~~~~~~~~~~ -:: - - $ cmake ../src -G Xcode -DBUILD_OPNAV=ON - -Linux Example -~~~~~~~~~~~~~ -:: - - $ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../src - -Windows Examples -~~~~~~~~~~~~~~~~ -- Example direct build on Windows:: - - cmake -G "Visual Studio Win" ../src -DCMAKE_BUILD_TYPE=Release - cmake --build . --target ALL_BUILD --config Release - -- Example ``cmake`` commands using x86:: - - cmake -G "Visual Studio Win32" ../src -DCMAKE_BUILD_TYPE=Release - - .. list-table:: MSVC Mapping - :widths: 25 25 - :header-rows: 1 - - * - MSVC Product Year - - MSVC Version - * - 2019 - - 16 - * - 2017 - - 15.9 - * - - - 15.8 - * - - - 15.7 - * - - - 15.6 - * - - - 15.5 - * - - - 15.4 - 15.3 - * - - - 15.2 - 15.0 - * - 2015 - - 14 - * - 2013 - - 12 - * - 2012 - - 11 - - - -Example build commands for Arch x86, MSVC Year 2017, MSVC Version 15:: - - cmake -G “Visual Studio 15 2017 Win32” ../src - -Example build commands forArch x64, MSVC Year 2019, MSVC Version 16:: - - cmake -G “Visual Studio 16 2019” -A x64 ../src -DCMAKE_BUILD_TYPE=Release - - cmake -G “Visual Studio 15 2017 Win64” ../src -DCMAKE_BUILD_TYPE=Release Running Project Tests --------------------- diff --git a/docs/source/Install/installBuildConan.rst b/docs/source/Install/installBuildConan.rst new file mode 100644 index 0000000000..eb74313f4f --- /dev/null +++ b/docs/source/Install/installBuildConan.rst @@ -0,0 +1,191 @@ +.. toctree:: + :hidden: + +.. _configureBuildConan: + +Advanced: Directly Building the Software Framework Using Conan +============================================================== + +.. warning:: + + This method of compiling Basilisk is not typically required and should only + be attempted by advanced users familiar with both ``conan`` and ``cmake``. + See :ref:`configureBuild` for documentation on the regular build process. + + +Configuring and Building with ``conan`` Commands +------------------------------------------------ +Calling ``conanfile.py`` with python executes a method that calls two separate ``conan`` function to setup and +configure process, and build the executable if desired. This section outlines this 2-step build process for +those that seek to build it this way. + +.. note:: + + All commands are called from the Basilisk root directory. + +Step 1: Installing Basilisk Dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The first command, in its minimalist form, is:: + + conan install . -if dist3/conan --build=missing + +This conan command will create the distribution folder, ``dist3`` in the above case, if needed, collect all the +require Basilisk 3rd party resources and compile them if their binaries are missing. The cmake files to access these +3rd party libraries are stored in ``dist3/conan``. + +There are several options that can be provided to this ``conan install`` command as shown in the following table. +Note that the option names for groupings of Basilisk modules are the same as with the one-step build above. + +.. list-table:: Options for ``conan install`` Step + :widths: 15 15 10 60 + :header-rows: 1 + + * - Option + - Values + - Default + - Description + * - ``-o vizInterface`` + - Boolean + - True + - Include :ref:`vizInterface` in the configuration and build + * - ``-o opNav`` + - Boolean + - False + - Include the `OpenCV `__ library dependent Basilisk modules. + * - ``-o clean`` + - Boolean + - False + - Delete the distribution folder before configuring to yield a fresh build + * - ``-o buildProject`` + - Boolean + - True + - Will build the project executable after the configuration step + * - ``-s build_type`` + - Release, Debug + - Release + - Specifies the build type + * - ``-o generator`` + - see `here `__ + - ``XCode`` (macOS), ``Visual Studio 16 2019`` (Windows), ``None`` (Linux) + - Used to specify a specific ``cmake`` generator. See discussion in Table :ref:`buildTable1Label`. + * - ``-o autoKey`` + - String 's' or 'u' + - Empty + - This is used to automatically respond to the python packaging installation requests to install the + package for the user (u) or system (s). + * - ``-o allOptPkg`` + - Boolean + - False + - Install all of the optional Basilisk python package dependencies + +Thus, using the same build example as in the one-step section, to create a build with ``opNav`` modes enabled, +but no :ref:`vizInterface`, and using a clean distribution folder, and that is built right away, you could use:: + + conan install . -if dist3/conan --build=missing -o clean=True -o buildProject=True -o opNav=True -o vizInterface=False + +Note how much more verbose this is, but it gives you full control if you want to store the compiled binaries and +cmake files in directories other than ``dist3/conan``. + +Step 2: Creating the IDE Project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The final step is to create the IDE project file and possibly build the executables directly. +At this stage there are no options to be provided. This step is done with:: + + conan build . -if dist3/conan + +.. warning:: + + If you want the ``conan build`` command to automatically compile the code, the ``buildProject`` option + must be set in the ``conan install`` step. + + +Running ``cmake`` Directly +-------------------------- + +The ``conan install`` command must always be run to install the required dependencies and compile them. If the +developer wishes, the ``cmake`` can be run directly from the ``dist3`` distribution folder instead +of relying on the ``conan build`` step discussed above. + +The following table summarizes the optional Basilisk related flags that can be provided to ``cmake``. If +they are not used, then the shown default behaviors are used. + +.. list-table:: ``cmake`` Basilisk Build Flags + :widths: 25 15 70 + :header-rows: 1 + + * - cmake Flag + - Default + - Description + * - ``BUILD_VIZINTERFACE`` + - ``ON`` + - will create :ref:`vizInterface` + * - ``BUILD_OPNAV`` + - ``OFF`` + - will create the OpenCL dependent optical navigation related modules + +macOS Example +~~~~~~~~~~~~~ +:: + + $ cmake ../src -G Xcode -DBUILD_OPNAV=ON + +Linux Example +~~~~~~~~~~~~~ +:: + + $ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../src + +Windows Examples +~~~~~~~~~~~~~~~~ +- Example direct build on Windows:: + + cmake -G "Visual Studio Win" ../src -DCMAKE_BUILD_TYPE=Release + cmake --build . --target ALL_BUILD --config Release + +- Example ``cmake`` commands using x86:: + + cmake -G "Visual Studio Win32" ../src -DCMAKE_BUILD_TYPE=Release + + .. list-table:: MSVC Mapping + :widths: 25 25 + :header-rows: 1 + + * - MSVC Product Year + - MSVC Version + * - 2022 + - 17 + * - 2019 + - 16 + * - 2017 + - 15.9 + * - + - 15.8 + * - + - 15.7 + * - + - 15.6 + * - + - 15.5 + * - + - 15.4 - 15.3 + * - + - 15.2 - 15.0 + * - 2015 + - 14 + * - 2013 + - 12 + * - 2012 + - 11 + + + +Example build commands for Arch x86, MSVC Year 2017, MSVC Version 15:: + + cmake -G “Visual Studio 15 2017 Win32” ../src + +Example build commands forArch x64, MSVC Year 2019, MSVC Version 16:: + + cmake -G “Visual Studio 16 2019” -A x64 ../src -DCMAKE_BUILD_TYPE=Release + + cmake -G “Visual Studio 15 2017 Win64” ../src -DCMAKE_BUILD_TYPE=Release + From 10e2495b47a4a77141d15df4d9de86807367d444 Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Wed, 20 Sep 2023 07:33:35 +0100 Subject: [PATCH 3/6] update Windows install instructions to clarify steps on setting PATH variables --- docs/source/Install/installOnWindows.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/Install/installOnWindows.rst b/docs/source/Install/installOnWindows.rst index 58336d0c2a..f163536325 100644 --- a/docs/source/Install/installOnWindows.rst +++ b/docs/source/Install/installOnWindows.rst @@ -53,9 +53,13 @@ Add SWIG and Basilisk paths into environment variables using the following steps - Under the Advanced tab, Select Environment Variables - Under the User (or System, depending on your setup) Variables panel, Select Path, and Click Edit - - Add the ``swig.exe`` directory to your path + - Add the ``swig.exe`` directory to your path. See this `site `__ + for more info on setting paths for swig. - add the path to ``CMake\bin``, such as ``C:\Program Files\CMake\bin`` - - Add the Basilisk library directory (``path2bsk/dist3/Basilisk``) to your path. Here, ``path2bsk`` is replaced with the actual path to the Basilisk folder. + - Add the Basilisk library directory (``path2bsk/dist3/Basilisk``) to your path. Here, + ``path2bsk`` is replaced with the actual path to the Basilisk folder. Note, the ``dist3`` folder does not + exist to begin with, but is created automatically when configuring Basilisk with ``python conanfile.py`` + as discussed below. For more information on how to configure the path Variable on Windows see this `help `__ link. From f4d7992de939ffa41bf7187bf069f02d444c812c Mon Sep 17 00:00:00 2001 From: Riccardo Date: Mon, 20 Nov 2023 10:03:03 -0700 Subject: [PATCH 4/6] Added definitions to CMEstDataMsgPayload variables --- .../msgPayloadDefC/CMEstDataMsgPayload.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/architecture/msgPayloadDefC/CMEstDataMsgPayload.h b/src/architecture/msgPayloadDefC/CMEstDataMsgPayload.h index 2b30060945..92ebbdeeac 100755 --- a/src/architecture/msgPayloadDefC/CMEstDataMsgPayload.h +++ b/src/architecture/msgPayloadDefC/CMEstDataMsgPayload.h @@ -22,12 +22,12 @@ /*! @brief Structure used to define CM estimation output data */ typedef struct { - double attError; - double state[3]; - double stateError[3]; - double covariance[3]; - double preFitRes[3]; - double postFitRes[3]; + double attError; //!< [-] attitude convergence error + double state[3]; //!< [m] estimated cm location + double stateError[3]; //!< [m] errpr w.r.t. truth + double covariance[3]; //!< [m^2] CM estimated covariance + double preFitRes[3]; //!< [Nm] pre-fit torque residuals + double postFitRes[3]; //!< [Nm] post-fit torque residuals }CMEstDataMsgPayload; From f3882819e805327d1bd7beacda30d5b29ed1e652 Mon Sep 17 00:00:00 2001 From: Riccardo Date: Mon, 20 Nov 2023 10:05:52 -0700 Subject: [PATCH 5/6] Added missing definitions to thrustCMEstimation.h --- .../thrustCMEstimation/thrustCMEstimation.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/fswAlgorithms/stateEstimation/thrustCMEstimation/thrustCMEstimation.h b/src/fswAlgorithms/stateEstimation/thrustCMEstimation/thrustCMEstimation.h index 3c64564b1d..d466b4ded7 100644 --- a/src/fswAlgorithms/stateEstimation/thrustCMEstimation/thrustCMEstimation.h +++ b/src/fswAlgorithms/stateEstimation/thrustCMEstimation/thrustCMEstimation.h @@ -53,13 +53,13 @@ class ThrustCMEstimation: public SysModel { /*! declare these user-defined quantities */ double attitudeTol; - ReadFunctor thrusterConfigBInMsg; - ReadFunctor intFeedbackTorqueInMsg; - ReadFunctor attGuidInMsg; - ReadFunctor vehConfigInMsg; - Message cmEstDataOutMsg; - Message vehConfigOutMsg; - VehicleConfigMsg_C vehConfigOutMsgC = {}; + ReadFunctor thrusterConfigBInMsg; //!< thr config in msg in B-frame coordinates + ReadFunctor intFeedbackTorqueInMsg; //!< integral feedback torque input msg + ReadFunctor attGuidInMsg; //!< attitude guidance input msg + ReadFunctor vehConfigInMsg; //!< (optional) vehicle configuration input msg + Message cmEstDataOutMsg; //!< estimated CM output msg + Message vehConfigOutMsg; //!< output C++ vehicle configuration msg + VehicleConfigMsg_C vehConfigOutMsgC = {}; //!< output C vehicle configuration msg Eigen::Vector3d r_CB_B; //!< initial CM estimate Eigen::Vector3d P0; //!< initial CM state covariance @@ -71,7 +71,7 @@ class ThrustCMEstimation: public SysModel { Eigen::Matrix3d R; //!< measurement noise covariance Eigen::Vector3d r_CB_est; //!< CM location estimate - bool cmKnowledge; + bool cmKnowledge; //!< boolean to assess if vehConfigInMsg is connected BSKLogger bskLogger; //!< -- BSK Logging }; From 735727691511beae3cad7c7e1021c17227a9ba36 Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Mon, 20 Nov 2023 17:36:26 -0700 Subject: [PATCH 6/6] fix documentation build warnings The class and a variable didn't have definitions --- src/simulation/dynamics/_GeneralModuleFiles/gravityModel.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/simulation/dynamics/_GeneralModuleFiles/gravityModel.h b/src/simulation/dynamics/_GeneralModuleFiles/gravityModel.h index 8169e95767..5788c0251f 100644 --- a/src/simulation/dynamics/_GeneralModuleFiles/gravityModel.h +++ b/src/simulation/dynamics/_GeneralModuleFiles/gravityModel.h @@ -29,7 +29,7 @@ class GravBodyData; -/** GravityModel is a purely abstract class the represents a mathematical body +/*! GravityModel is a purely abstract class the represents a mathematical body * for computing the gravity field generated by a body at some arbitrary * point in space. */ @@ -84,7 +84,7 @@ class GravityModel { virtual double computePotentialEnergy(const Eigen::Vector3d& positionWrtPlanet_N) const = 0; public: - BSKLogger *bskLogger; + BSKLogger *bskLogger; /*!< pointer to bsk logging instance */ }; #endif /* GRAVITY_MODEL_H */