Last pass at documenting the cmake stuff

cmake/CPackSignAndNotarizeDmg.cmake

@@ -10,7 +10,7 @@ To do so, it uses the `CodeSigning`_ functions :cmake:command:`codesign_files_ma
 
 It requires that this be set: :cmake:variable:`CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION`
 
-And it will only notarize if this is set :cmake:variable:`CPACK_CODESIGNING_NOTARY_PROFILE_NAME`
+And it will only notarize if this is set: :cmake:variable:`CPACK_CODESIGNING_NOTARY_PROFILE_NAME`
 
 #]=======================================================================]
 message(STATUS "The message from ${CMAKE_CURRENT_LIST_FILE} and generator ${CPACK_GENERATOR}")

cmake/CodeSigning.cmake

@@ -111,7 +111,7 @@ This module defines functions to codesign, notarize and staple macOS files.
   It is necessary to have issued an ``install(TARGET <TARGET_NAME> DESTINATION <DESTINATION>)`` command before calling this function,
   and done any call to ``fixup_executable`` or ``install_name_tool`` that would invalidate the signature.
 
-  This function will therefore run in the _CPack staging area, after any rpath adjustments, and ensure the signature sticks.
+  This function will therefore run in the CPack staging area, after any rpath adjustments, and ensure the signature sticks.
 
   It will only do something on ``APPLE`` and if :cmake:variable:`CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION` is defined.
 

cmake/Install.cmake

@@ -697,31 +697,30 @@ if(APPLE)
 
   if(CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION)
     set(FILES_TO_SIGN
-      #$<TARGET_FILE_NAME:ConvertInputFormat> # "ConvertInputFormat-24.2.0"
-      #$<TARGET_FILE_NAME:energyplus> # energyplus-24.2.0"
-      #$<TARGET_FILE_NAME:energyplusapi># "libenergyplusapi.24.2.0.dylib"
+      # Targets are signed already via register_install_codesign_target
+      #$<TARGET_FILE_NAME:ConvertInputFormat>
+      #$<TARGET_FILE_NAME:energyplus>
+      #$<TARGET_FILE_NAME:energyplusapi>
 
       # Bash scripts, not sure if needed or not
       "runenergyplus"
       "runepmacro"
       "runreadvars"
-      # Already signed because just copied from bin to package
+      # Copied-verbatim apps: Already signed because just copied from bin to package
       # "EPMacro"
       # "PreProcess/EP-Launch-Lite.app"
       # "PreProcess/IDFVersionUpdater/IDFVersionUpdater.app"
       # "PostProcess/EP-Compare/EP-Compare.app"
     )
 
-    # Codesign inner binaries and libraries, in the staging area
-    # set(CODESIGNING_CMAKE_FILE "${CMAKE_CURRENT_LIST_DIR}/CodeSigning.cmake")
-    # Define some variables for the script
+    # Codesign inner binaries and libraries, in the CPack staging area for the EnergyPlus project, component Unspecified
+    # Define some required variables for the script in the scope of the install(SCRIPT) first
     install(CODE "set(CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION \"${CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION}\")" COMPONENT Unspecified)
-    install(CODE "set(CPACK_CODESIGNING_NOTARY_PROFILE_NAME \"${CPACK_CODESIGNING_NOTARY_PROFILE_NAME}\")" COMPONENT Unspecified)
     install(CODE "set(FILES_TO_SIGN \"${FILES_TO_SIGN}\")" COMPONENT Unspecified)
-    install(CODE "set(BUILD_FORTRAN \"${BUILD_FORTRAN}\")" COMPONENT Unspecified)
     # call the script
     install(SCRIPT "${CMAKE_CURRENT_LIST_DIR}/install_codesign_script.cmake" COMPONENT Unspecified)
 
+    # Register the CPACK_POST_BUILD_SCRIPTS
     set(CPACK_POST_BUILD_SCRIPTS "${CMAKE_CURRENT_LIST_DIR}/CPackSignAndNotarizeDmg.cmake")
 
   endif()

cmake/codesign_doc/build_codesign_doc.sh

@@ -1,3 +1,3 @@
-pip install sphinx sphinxcontrib-moderncmakedomain sphinx-sitemap GitPython sphinx-rtd-theme breathe rst2pdf
+pip install -r requirements.txt
 sphinx-build -M html $(pwd) out
 sphinx-build -b pdf  $(pwd) out

cmake/codesign_doc/conf.py

@@ -76,7 +76,7 @@
 
 source_suffix = '.rst'
 # Doxygen
-subprocess.call('doxygen Doxyfile', shell=True)
+# subprocess.call('doxygen Doxyfile', shell=True)
 
 # -- Project information -----------------------------------------------------
 
@@ -103,7 +103,6 @@
     'sphinx.ext.viewcode',
     #'sphinx_sitemap',
     'sphinx.ext.inheritance_diagram',
-    'breathe',
     'sphinxcontrib.moderncmakedomain',
     'rst2pdf.pdfbuilder',
 ]
@@ -130,14 +129,14 @@
     'analytics_id': '',  #  Provided by Google in your dashboard
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
-    'style_external_links': False,
+    'style_external_links': True,
 
     'logo_only': False,
 
     # Toc options
     'collapse_navigation': True,
     'sticky_navigation': True,
-    'navigation_depth': 4,
+    'navigation_depth': -1,
     'includehidden': True,
     'titles_only': False
 }
@@ -155,16 +154,6 @@
 #     'js/version_switcher.js',
 # ]
 
-# -- Breathe configuration -------------------------------------------------
-
-master_doc = 'index'
-
-breathe_projects = {
-	'C++ Sphinx Doxygen Breathe': "@conf_out_path@/xml/"
-}
-breathe_default_project = 'C++ Sphinx Doxygen Breathe'
-breathe_default_members = ('members', 'undoc-members')
-
 ############################
 # SETUP THE RTD LOWER-LEFT #
 ############################

cmake/codesign_doc/index.rst

@@ -1,33 +1,39 @@
-Welcome to CMake Custom Modules documentation
-======================================================
+CMake Custom Codesigning Modules documentation
+=========================================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+.. only:: html
 
-.. cmake-manual-description: CMake Modules Reference
+   .. contents:: Table of Contents
 
-CMake Modules
-*************
+Influencial Configuration Variables
+*************************************
 
-Below you find a list of CMake Modules included in this project.
-
-Codesigning Modules
-^^^^^^^^^^^^^^^^^^^
-
-Influencial configuration variables
+Influencial configuration variables on macOS
 
 .. cmake:variable:: CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION
 
   This is something like ``Developer ID Application: <The Name> (<TEAMID>)``.
   Refer to :cmake:command:`setup_macos_codesigning_variables` which pre-populates it with options from ``security-find-identity -v -p codesign``
 
+  This will automatically set `CPACK_IFW_PACKAGE_SIGNING_IDENTITY <https://cmake.org/cmake/help/v3.30/cpack_gen/ifw.html#variable:CPACK_IFW_PACKAGE_SIGNING_IDENTITY>`_ to the same value, so that ``binarycreator`` signs the .app installer it builds as well
+
 .. cmake:variable:: CPACK_CODESIGNING_NOTARY_PROFILE_NAME
 
   Should be set to the name you used during ``xcrun notarytool store-credentials``
 
-Here is the list of Utility Modules
+-------
 
+Codesigning Modules
+*******************
 .. cmake-module:: ../CodeSigning.cmake
 
+-------
+
+Codesigning Scripts
+*******************
+
 .. cmake-module:: ../CPackSignAndNotarizeDmg.cmake
+
+-------
+
+.. cmake-module:: ../install_codesign_script.cmake

cmake/codesign_doc/requirements.txt

@@ -0,0 +1,5 @@
+GitPython==3.1.43
+rst2pdf==0.102
+sphinx-rtd-theme==2.0.0
+sphinx-sitemap==2.6.0
+sphinxcontrib-moderncmakedomain==3.29.0

cmake/install_codesign_script.cmake

@@ -1,21 +1,46 @@
-message("Codesigning inner executables and library from ${CMAKE_CURRENT_LIST_FILE}")
+#[=======================================================================[.rst:
+install_codesign_script
+-----------------------
 
-message("CMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX}")
-message("CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION=${CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION}")
-message("BUILD_FORTRAN=${BUILD_FORTRAN}")
+This file is meant to be used up as a ``install(SCRIPT)``
 
-if(NOT CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION)
-  message(FATAL_ERROR "CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION is required")
-endif()
+Pre-conditions:
 
-if(NOT FILES_TO_SIGN)
-  message(FATAL_ERROR "FILES_TO_SIGN is required")
-endif()
+- It requires that you're running on ``APPLE``
 
-if(NOT BUILD_FORTRAN)
-  message(FATAL_ERROR "BUILD_FORTRAN is required")
-endif()
+- **Important: In the scope of this** ``install(SCRIPT)``, you must define
+
+    * :cmake:variable:`CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION`
+    * You need to also set a variable ``FILES_TO_SIGN``
+
+**In the scope** meaning that you have to issue some ``install(CODE ..)`` commands prior to calling it, and they must be:
+
+    * Part of the same ``project()``
+    * Using the same CPack ``COMPONENT``
+
+This script will codesign the ``FILES_TO_SIGN``, as well as the globbed copied Python .so and the root dylibs (such as ``libintl8.dylib``)
+
+* ``python_standard_lib/lib-dynload/*.so``
+* ``lib*.dylib``
+
+To do so, it uses the `CodeSigning`_ functions :cmake:command:`codesign_files_macos`
 
+This script will therefore run in the CPack staging area, and should be added after installation of the Python sos and root dylib,
+after any rpath adjustments, to ensure the signature sticks.
+
+Usage::
+
+  if(APPLE AND CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION)
+    set(FILES_TO_SIGN "fileA" "fileB")
+    install(CODE "set(CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION \"${CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION}\")" COMPONENT Unspecified)
+    install(CODE "set(FILES_TO_SIGN \"${FILES_TO_SIGN}\")" COMPONENT Unspecified)
+    # call the script
+    install(SCRIPT "${CMAKE_CURRENT_LIST_DIR}/install_codesign_script.cmake" COMPONENT Unspecified)
+  endif()
+#]=======================================================================]
+
+#------------------------------------------------------------------------------
+# Just a helper
 function(print_relative_paths)
   set(prefix "")
   set(valueLessKeywords NAME_ONLY NEWLINE)
@@ -58,7 +83,20 @@ function(print_relative_paths)
     message("${_PREFIX}${rel_paths}")
   endif()
 endfunction()
+#------------------------------------------------------------------------------
+
+message("Codesigning inner executables and library from ${CMAKE_CURRENT_LIST_FILE}")
+
+message("CMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX}")
+message("CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION=${CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION}")
+
+if(NOT CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION)
+  message(FATAL_ERROR "CPACK_CODESIGNING_DEVELOPPER_ID_APPLICATION is required")
+endif()
 
+if(NOT FILES_TO_SIGN)
+  message(FATAL_ERROR "FILES_TO_SIGN is required")
+endif()
 
 foreach(path ${FILES_TO_SIGN})
   list(APPEND FULL_PATHS "${CMAKE_INSTALL_PREFIX}/${path}")