diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/cpack_gen/innosetup.rst | 420 | ||||
| -rw-r--r-- | Help/guide/tutorial/Adding Generator Expressions.rst | 191 | ||||
| -rw-r--r-- | Help/guide/tutorial/Adding Usage Requirements for a Library.rst | 188 | ||||
| -rw-r--r-- | Help/guide/tutorial/Adding a Library.rst | 5 | ||||
| -rw-r--r-- | Help/guide/tutorial/Step3/CMakeLists.txt | 8 | ||||
| -rw-r--r-- | Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt | 4 | ||||
| -rw-r--r-- | Help/guide/tutorial/Step4/CMakeLists.txt | 22 | ||||
| -rw-r--r-- | Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt | 7 | ||||
| -rw-r--r-- | Help/manual/cpack-generators.7.rst | 1 | ||||
| -rw-r--r-- | Help/release/dev/cpack-innosetup.rst | 12 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LANG_COMPILER_ID.rst | 3 |
11 files changed, 659 insertions, 202 deletions
diff --git a/Help/cpack_gen/innosetup.rst b/Help/cpack_gen/innosetup.rst new file mode 100644 index 0000000..f48e7f5 --- /dev/null +++ b/Help/cpack_gen/innosetup.rst @@ -0,0 +1,420 @@ +CPack Inno Setup Generator +-------------------------- + +.. versionadded:: 3.27 + +Inno Setup is a free installer for Windows programs by Jordan Russell and +Martijn Laan (https://jrsoftware.org/isinfo.php). + +This documentation explains Inno Setup generator specific options. + +The generator provides a lot of options like components. Unfortunately, not +all features (e.g. component dependencies) are currently supported by +Inno Setup and they're ignored by the generator for now. + +CPack requires Inno Setup 6 or greater and only works on Windows. + +Variables specific to CPack Inno Setup generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can use the following variables to change the behavior of the CPack +``INNOSETUP`` generator: + + +General +""""""" + +None of the following variables is required to be set for the Inno Setup +generator to work. If a variable is marked as mandatory below but not set, +its default value is taken. + +The variables can also contain Inno Setup constants like ``{app}``. Please +refer to the documentation of Inno Setup for more information. + +If you're asked to provide the path to any file, you can always give an +absolute path or in most cases the relative path from the top-level directory +where all files being installed by an :command:`install` instruction reside. + +CPack tries to escape quotes and other special characters for you. However, +using special characters could cause problems. + +The following variable simplifies the usage of Inno Setup in CMake: + +.. variable:: CPACK_INNOSETUP_USE_CMAKE_BOOL_FORMAT + + Inno Setup only uses ``yes`` or ``no`` as boolean formats meanwhile CMake + uses a lot of alternative formats like ``ON`` or ``OFF``. Having this option + turned on enables an automatic conversion. + + Consider the following example: + + .. code-block:: cmake + + set(CMAKE_INNOSETUP_SETUP_AllowNoIcons OFF) + + If this option is turned on, the following line will be created in the output + script: ``AllowNoIcons=no``. + Else, the following erroneous line will be created: ``AllowNoIcons=OFF`` + + The conversion is enabled in every Inno Setup specific variable. + + :Mandatory: Yes + :Default: ``ON`` + + +Setup Specific Variables +"""""""""""""""""""""""" + +.. variable:: CPACK_INNOSETUP_ARCHITECTURE + + One of ``x86``, ``x64``, ``arm64`` or ``ia64``. This variable specifies the + target architecture of the installer. This also affects the Program Files + folder or registry keys being used. + + CPack tries to determine the correct value with a try compile (see + :variable:`CMAKE_SIZEOF_VOID_P`), but this option can be manually specified + too (especially when using ``ia64`` or cross-platform compilation). + + :Mandatory: Yes + :Default: Either ``x86`` or ``x64`` depending on the results of the try-compile + +.. variable:: CPACK_INNOSETUP_INSTALL_ROOT + + If you don't want the installer to create the installation directory under + Program Files, you've to specify the installation root here. + + The full directory of the installation will be: + ``${CPACK_INNOSETUP_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}``. + + :Mandatory: Yes + :Default: ``{autopf}`` + +.. variable:: CPACK_INNOSETUP_ALLOW_CUSTOM_DIRECTORY + + If turned on, the installer allows the user to change the installation + directory providing an extra wizard page. + + :Mandatory: Yes + :Default: ``ON`` + +.. variable:: CPACK_INNOSETUP_PROGRAM_MENU_FOLDER + + The initial name of the start menu folder being created. + + If this variable is set to ``.``, then no separate folder is created, + application shortcuts will appear in the top-level start menu folder. + + :Mandatory: Yes + :Default: The value of :variable:`CPACK_PACKAGE_NAME` + +.. variable:: CPACK_INNOSETUP_LANGUAGES + + A :ref:`semicolon-separated list <CMake Language Lists>` of languages you want + Inno Setup to include. + + Currently available: ``armenian``, ``brazilianPortuguese``, ``bulgarian``, + ``catalan``, ``corsican``, ``czech``, ``danish``, ``dutch``, ``english``, + ``finnish``, ``french``, ``german``, ``hebrew``, ``icelandic``, ``italian``, + ``japanese``, ``norwegian``, ``polish``, ``portuguese``, ``russian``, + ``slovak``, ``slovenian``, ``spanish``, ``turkish`` and ``ukrainian``. + This list might differ depending on the version of Inno Setup. + + :Mandatory: Yes + :Default: ``english`` + +.. variable:: CPACK_INNOSETUP_IGNORE_LICENSE_PAGE + + If you don't specify a license file using + :variable:`CPACK_RESOURCE_FILE_LICENSE`, CPack uses a file for demonstration + purposes. If you want the installer to ignore license files at all, you can + enable this option. + + :Mandatory: Yes + :Default: ``OFF`` + +.. variable:: CPACK_INNOSETUP_IGNORE_README_PAGE + + If you don't specify a readme file using + :variable:`CPACK_RESOURCE_FILE_README`, CPack uses a file for demonstration + purposes. If you want the installer to ignore readme files at all, you can + enable this option. Make sure the option is disabled when using + a custom readme file. + + :Mandatory: Yes + :Default: ``ON`` + +.. variable:: CPACK_INNOSETUP_PASSWORD + + Enables password protection and file encryption with the given password. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_USE_MODERN_WIZARD + + Enables the modern look and feel provided by Inno Setup. If this option is + turned off, the classic style is used instead. Images and icon files are + also affected. + + :Mandatory: Yes + :Default: ``OFF`` because of compatibility reasons + +.. variable:: CPACK_INNOSETUP_ICON_FILE + + The path to a custom installer ``.ico`` file. + + Use :variable:`CPACK_PACKAGE_ICON` to customize the bitmap file being shown + in the wizard. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_SETUP_<directive> + + This group allows adapting any of the ``[Setup]`` section directives provided + by Inno Setup where ``directive`` is its name. + + Here are some examples: + + .. code-block:: cmake + + set(CPACK_INNOSETUP_SETUP_WizardSmallImageFile "my_bitmap.bmp") + set(CPACK_INNOSETUP_SETUP_AllowNoIcons OFF) # This requires CPACK_INNOSETUP_USE_CMAKE_BOOL_FORMAT to be on + + All of these variables have higher priority than the others. + Consider the following example: + + .. code-block:: cmake + + set(CPACK_INNOSETUP_SETUP_Password "admin") + set(CPACK_INNOSETUP_PASSWORD "secret") + + The password will be ``admin`` at the end because ``CPACK_INNOSETUP_PASSWORD`` + has less priority than ``CPACK_INNOSETUP_SETUP_Password``. + + :Mandatory: No + + +File Specific Variables +""""""""""""""""""""""" + +Although all files being installed by an :command:`install` instruction are +automatically processed and added to the installer, there are some variables +to customize the installation process. + +Before using executables (only ``.exe`` or ``.com``) in shortcuts +(e.g. :variable:`CPACK_CREATE_DESKTOP_LINKS`) or ``[Run]`` entries, you've to +add the raw file name (without path and extension) to +:variable:`CPACK_PACKAGE_EXECUTABLES` and create a start menu shortcut +for them. + +If you have two files with the same raw name (e.g. ``a/executable.exe`` and +``b/executable.com``), an entry in the section is created twice. This will +result in undefined behavior and is not recommended. + +.. variable:: CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS + + This variable should contain a + :ref:`semicolon-separated list <CMake Language Lists>` of pairs ``path``, + ``instruction`` and can be used to customize the install command being + automatically created for each file or directory. + + CPack creates the following Inno Setup instruction for every file... + + .. code-block:: + + Source: "absolute\path\to\my_file.txt"; DestDir: "{app}"; Flags: ignoreversion + + ...and the following line for every directory: + + .. code-block:: + + Name: "{app}\my_folder" + + You might want to change the destination directory or the flags of + ``my_file.txt``. Since we can also provide a relative path, the line you'd + like to have, is the following: + + .. code-block:: + + Source: "my_file.txt"; DestDir: "{userdocs}"; Flags: ignoreversion uninsneveruninstall + + You would do this by using ``my_file.txt`` as ``path`` and + ``Source: "my_file.txt"; DestDir: "{userdocs}"; Flags: ignoreversion uninsneveruninstall`` + as ``instruction``. + + You've to take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_. + So the CMake command would be: + + .. code-block:: cmake + + set(CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS "my_file.txt;Source: \\\"my_file.txt\\\"\\; DestDir: \\\"{userdocs}\\\"\\; Flags: ignoreversion uninsneveruninstall") + + To improve readability, you should go around the escaping problem by using + :variable:`CPACK_VERBATIM_VARIABLES` or by placing the instruction into a + separate CPack project config file. + + If you customize the install instruction of a specific file, you lose the + connection to its component. To go around, manually add + ``Components: <component>``. You also need to add its shortcuts and ``[Run]`` + entries by yourself in a custom section, since the executable won't be found + anymore by :variable:`CPACK_PACKAGE_EXECUTABLES`. + + Here's another example (Note: You've to go around the escaping problem for + the example to work): + + .. code-block:: cmake + + set(CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS + "component1/my_folder" "Name: \"{userdocs}\\my_folder\"\; Components: component1" + "component2/my_folder2/my_file.txt" "Source: \"component2\\my_folder2\\my_file.txt\"\; DestDir: \"{app}\\my_folder2\\my_file.txt\"\; Flags: ignoreversion uninsneveruninstall\; Components: component2") + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_MENU_LINKS + + This variable should contain a + :ref:`semicolon-separated list <CMake Language Lists>` of pairs ``link``, + ``link name`` and can be used to add shortcuts into the start menu folder + beside those of the executables (see :variable:`CPACK_PACKAGE_EXECUTABLES`). + While ``link name`` is the label, ``link`` can be a URL or a path relative to + the installation directory. + + Here's an example: + + .. code-block:: cmake + + set(CPACK_INNOSETUP_MENU_LINKS + "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html" + "CMake Help" "https://cmake.org" "CMake Web Site") + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_CREATE_UNINSTALL_LINK + + If this option is turned on, a shortcut to the application's uninstaller is + automatically added to the start menu folder. + + :Mandatory: Yes + :Default: ``OFF`` + +.. variable:: CPACK_INNOSETUP_RUN_EXECUTABLES + + A :ref:`semicolon-separated list <CMake Language Lists>` of executables being + specified in :variable:`CPACK_PACKAGE_EXECUTABLES` which the user can run + when the installer finishes. + + They're internally added to the ``[Run]`` section. + + :Mandatory: No + + +Components Specific Variables +""""""""""""""""""""""""""""" + +The generator supports components and also downloaded components. However, +there are some features of components that aren't supported yet (especially +component dependencies). These variables are ignored for now. + +CPack will change a component's name in Inno Setup if it has a parent group +for technical reasons. Consider using ``group\component`` as component name in +Inno Setup scripts if you have the component ``component`` and its parent +group ``group``. + +Here are some additional variables for components: + +.. variable:: CPACK_INNOSETUP_<compName>_INSTALL_DIRECTORY + + If you don't want the component ``compName`` to be installed under ``{app}``, + you've to specify its installation directory here. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_VERIFY_DOWNLOADS + + This option only affects downloaded components. + + If this option is turned on, the hashes of the downloaded archives are + calculated during compile and + download time. The installer will only proceed if they match. + + :Mandatory: Yes + :Default: ``ON`` + + +Compilation and Scripting Specific Variables +"""""""""""""""""""""""""""""""""""""""""""" + +.. variable:: CPACK_INNOSETUP_EXECUTABLE + + The filename of the Inno Setup Script Compiler command. + + :Mandatory: Yes + :Default: ``ISCC`` + +.. variable:: CPACK_INNOSETUP_EXECUTABLE_ARGUMENTS + + A :ref:`semicolon-separated list <CMake Language Lists>` of extra + command-line options for the Inno Setup Script Compiler command. + + For example: ``/Qp;/Smysigntool=$p`` + + Take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_DEFINE_<macro> + + This group allows to add custom define directives as command-line options to + the Inno Setup Preprocessor command. Each entry emulates a + ``#define public <macro>`` directive. Its macro is accessible from anywhere + (``public``), so it can also be used in extra script files. + + Macro names must not contain any special characters. Refer to the Inno Setup + Preprocessor documentation for the detailed rules. + + Consider the following example: + + .. code-block:: cmake + + # The following line emulates: #define public MyMacro "Hello, World!" + set(CPACK_INNOSETUP_DEFINE_MyMacro "Hello, World!") + + At this point, you can use ``MyMacro`` anywhere. For example in the following + extra script: + + .. code-block:: + + AppComments={#emit "'My Macro' has the value: " + MyMacro} + + Take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_EXTRA_SCRIPTS + + A :ref:`semicolon-separated list <CMake Language Lists>` of paths to + additional ``.iss`` script files to be processed. + + They're internally included at the top of the output script file using a + ``#include`` directive. + + You can add any section in your file to extend the installer (e.g. adding + additional tasks or registry keys). Prefer using + :variable:`CPACK_INNOSETUP_SETUP_<directive>` when extending the + ``[Setup]`` section. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_CODE_FILES + + A :ref:`semicolon-separated list <CMake Language Lists>` of paths to + additional Pascal files to be processed. + + This variable is actually the same as + :variable:`CPACK_INNOSETUP_EXTRA_SCRIPTS`, except you don't have to + add ``[Code]`` at the top of your file. Never change the current section in + a code file. This will result in undefined behavior! Treat them as normal + Pascal scripts instead. + + Code files are included at the very bottom of the output script. + + :Mandatory: No diff --git a/Help/guide/tutorial/Adding Generator Expressions.rst b/Help/guide/tutorial/Adding Generator Expressions.rst index aba9f7a..3dab97f 100644 --- a/Help/guide/tutorial/Adding Generator Expressions.rst +++ b/Help/guide/tutorial/Adding Generator Expressions.rst @@ -27,168 +27,7 @@ expressions are the ``0`` and ``1`` expressions. A ``$<0:...>`` results in the empty string, and ``<1:...>`` results in the content of ``...``. They can also be nested. -Exercise 1 - Setting the C++ Standard with Interface Libraries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Before we use :manual:`generator expressions <cmake-generator-expressions(7)>` -let's refactor our existing code to use an ``INTERFACE`` library. We will -use that library in the next step to demonstrate a common use for -:manual:`generator expressions <cmake-generator-expressions(7)>`. - -Goal ----- - -Add an ``INTERFACE`` library target to specify the required C++ standard. - -Helpful Resources ------------------ - -* :command:`add_library` -* :command:`target_compile_features` -* :command:`target_link_libraries` - -Files to Edit -------------- - -* ``CMakeLists.txt`` -* ``MathFunctions/CMakeLists.txt`` - -Getting Started ---------------- - -In this exercise, we will refactor our code to use an ``INTERFACE`` library to -specify the C++ standard. - -The starting source code is provided in the ``Step4`` directory. In this -exercise, complete ``TODO 1`` through ``TODO 3``. - -Start by editing the top level ``CMakeLists.txt`` file. Construct an -``INTERFACE`` library target called ``tutorial_compiler_flags`` and -specify ``cxx_std_11`` as a target compiler feature. - -Modify ``CMakeLists.txt`` and ``MathFunctions/CMakeLists.txt`` so that all -targets have a :command:`target_link_libraries` call to -``tutorial_compiler_flags``. - -Build and Run -------------- - -Make a new directory called ``Step4_build``, run the :manual:`cmake <cmake(1)>` -executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project -and then build it with your chosen build tool or by using ``cmake --build .`` -from the build directory. - -Here's a refresher of what that looks like from the command line: - -.. code-block:: console - - mkdir Step4_build - cd Step4_build - cmake ../Step4 - cmake --build . - -Next, use the newly built ``Tutorial`` and verify that it is working as -expected. - -Solution --------- - -Let's update our code from the previous step to use interface libraries -to set our C++ requirements. - -To start, we need to remove the two :command:`set` calls on the variables -:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`. -The specific lines to remove are as follows: - -.. literalinclude:: Step4/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-CXX_STANDARD-variable-remove - :language: cmake - :start-after: # specify the C++ standard - :end-before: # TODO 6: Create helper variables - -Next, we need to create an interface library, ``tutorial_compiler_flags``. And -then use :command:`target_compile_features` to add the compiler feature -``cxx_std_11``. - - -.. raw:: html - - <details><summary>TODO 1: Click to show/hide answer</summary> - -.. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 1: CMakeLists.txt - :name: CMakeLists.txt-cxx_std-feature - :language: cmake - :start-after: # specify the C++ standard - :end-before: # add compiler warning flags just - -.. raw:: html - - </details> - -Finally, with our interface library set up, we need to link our -executable ``Target``, our ``MathFunctions`` library, and our ``SqrtLibrary`` -library to our new -``tutorial_compiler_flags`` library. Respectively, the code will look like -this: - -.. raw:: html - - <details><summary>TODO 2: Click to show/hide answer</summary> - -.. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 2: CMakeLists.txt - :name: CMakeLists.txt-target_link_libraries-step4 - :language: cmake - :start-after: add_executable(Tutorial tutorial.cxx) - :end-before: # add the binary tree to the search path for include file - -.. raw:: html - - </details> - -this: - -.. raw:: html - - <details><summary>TODO 3: Click to show/hide answer</summary> - -.. literalinclude:: Step5/MathFunctions/CMakeLists.txt - :caption: TODO 3: MathFunctions/CMakeLists.txt - :name: MathFunctions-CMakeLists.txt-target_link_libraries-step4 - :language: cmake - :start-after: # link our compiler flags interface library - :end-before: target_link_libraries(MathFunctions - -.. raw:: html - - </details> - -and this: - -.. raw:: html - - <details><summary>TODO 4: Click to show/hide answer</summary> - -.. literalinclude:: Step5/MathFunctions/CMakeLists.txt - :caption: TODO 4: MathFunctions/CMakeLists.txt - :name: MathFunctions-SqrtLibrary-target_link_libraries-step4 - :language: cmake - :start-after: target_link_libraries(SqrtLibrary - :end-before: endif() - -.. raw:: html - - </details> - - -With this, all of our code still requires C++ 11 to build. Notice -though that with this method, it gives us the ability to be specific about -which targets get specific requirements. In addition, we create a single -source of truth in our interface library. - -Exercise 2 - Adding Compiler Warning Flags with Generator Expressions +Exercise 1 - Adding Compiler Warning Flags with Generator Expressions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A common usage of @@ -218,8 +57,8 @@ Files to Edit Getting Started --------------- -Start with the resulting files from Exercise 1. Complete ``TODO 5`` through -``TODO 8``. +Open the file ``Step4/CMakeLists.txt`` and complete ``TODO 1`` through +``TODO 4``. First, in the top level ``CMakeLists.txt`` file, we need to set the :command:`cmake_minimum_required` to ``3.15``. In this exercise we are going @@ -233,12 +72,16 @@ given a language and a set of compiler ids. Build and Run ------------- -Since we have our build directory already configured from Exercise 1, simply -rebuild our code by calling the following: +Make a new directory called ``Step4_build``, run the :manual:`cmake <cmake(1)>` +executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project +and then build it with your chosen build tool or by using ``cmake --build .`` +from the build directory. .. code-block:: console + mkdir Step4_build cd Step4_build + cmake ../Step4 cmake --build . Solution @@ -249,10 +92,10 @@ version ``3.15``: .. raw:: html - <details><summary>TODO 5: Click to show/hide answer</summary> + <details><summary>TODO 1: Click to show/hide answer</summary> .. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 5: CMakeLists.txt + :caption: TODO 1: CMakeLists.txt :name: MathFunctions-CMakeLists.txt-minimum-required-step4 :language: cmake :end-before: # set the project name and version @@ -268,10 +111,10 @@ variables ``gcc_like_cxx`` and ``msvc_cxx`` as follows: .. raw:: html - <details><summary>TODO 6: Click to show/hide answer</summary> + <details><summary>TODO 2: Click to show/hide answer</summary> .. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 6: CMakeLists.txt + :caption: TODO 2: CMakeLists.txt :name: CMakeLists.txt-compile_lang_and_id :language: cmake :start-after: # the BUILD_INTERFACE genex @@ -289,10 +132,10 @@ interface library. .. raw:: html - <details><summary>TODO 7: Click to show/hide answer</summary> + <details><summary>TODO 3: Click to show/hide answer</summary> .. code-block:: cmake - :caption: TODO 7: CMakeLists.txt + :caption: TODO 3: CMakeLists.txt :name: CMakeLists.txt-compile_flags target_compile_options(tutorial_compiler_flags INTERFACE @@ -311,10 +154,10 @@ condition. The resulting full code looks like the following: .. raw:: html - <details><summary>TODO 8: Click to show/hide answer</summary> + <details><summary>TODO 4: Click to show/hide answer</summary> .. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 8: CMakeLists.txt + :caption: TODO 4: CMakeLists.txt :name: CMakeLists.txt-target_compile_options-genex :language: cmake :start-after: set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst index 74b7496..2273063 100644 --- a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst @@ -100,7 +100,7 @@ follows: :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE :language: cmake :start-after: # to find MathFunctions.h - :end-before: option + :end-before: # should we use our own .. raw:: html @@ -108,24 +108,26 @@ follows: Now that we've specified usage requirements for ``MathFunctions`` we can safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level -``CMakeLists.txt``, here: +``CMakeLists.txt``. + +Remove this line: .. raw:: html <details><summary>TODO 2: Click to show/hide answer</summary> -.. literalinclude:: Step4/CMakeLists.txt +.. literalinclude:: Step3/CMakeLists.txt :caption: TODO 2: CMakeLists.txt :name: CMakeLists.txt-remove-EXTRA_INCLUDES :language: cmake - :start-after: # add the MathFunctions library - :end-before: # TODO 2: Link to tutorial_compiler_flags + :start-after: add_subdirectory(MathFunctions) + :end-before: # add the executable .. raw:: html </details> -And here: +And the lines: .. raw:: html @@ -141,7 +143,181 @@ And here: </details> +The remaining code looks like: + +.. raw:: html + + <details><summary>Click to show/hide the resulting code</summary> + +.. literalinclude:: Step4/CMakeLists.txt + :caption: Remaining code after removing EXTRA_INCLUDES + :name: CMakeLists.txt-after-removing-EXTRA_INCLUDES + :language: cmake + :start-after: add_subdirectory(MathFunctions) + +.. raw:: html + + </details> + + Notice that with this technique, the only thing our executable target does to use our library is call :command:`target_link_libraries` with the name of the library target. In larger projects, the classic method of specifying library dependencies manually becomes very complicated very quickly. + +Exercise 2 - Setting the C++ Standard with Interface Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Now that we have switched our code to a more modern approach, let's demonstrate +a modern technique to set properties to multiple targets. + +Let's refactor our existing code to use an ``INTERFACE`` library. We will +use that library in the next step to demonstrate a common use for +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +Goal +---- + +Add an ``INTERFACE`` library target to specify the required C++ standard. + +Helpful Resources +----------------- + +* :command:`add_library` +* :command:`target_compile_features` +* :command:`target_link_libraries` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``MathFunctions/CMakeLists.txt`` + +Getting Started +--------------- + +In this exercise, we will refactor our code to use an ``INTERFACE`` library to +specify the C++ standard. + +Start this exercise from what we left at the end of Step3 exercise 1. You will +have to complete ``TODO 4`` through ``TODO 7``. + +Start by editing the top level ``CMakeLists.txt`` file. Construct an +``INTERFACE`` library target called ``tutorial_compiler_flags`` and +specify ``cxx_std_11`` as a target compiler feature. + +Modify ``CMakeLists.txt`` and ``MathFunctions/CMakeLists.txt`` so that all +targets have a :command:`target_link_libraries` call to +``tutorial_compiler_flags``. + +Build and Run +------------- + +Since we have our build directory already configured from Exercise 1, simply +rebuild our code by calling the following: + +.. code-block:: console + + cd Step3_build + cmake --build . + +Next, use the newly built ``Tutorial`` and verify that it is working as +expected. + +Solution +-------- + +Let's update our code from the previous step to use interface libraries +to set our C++ requirements. + +To start, we need to remove the two :command:`set` calls on the variables +:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`. +The specific lines to remove are as follows: + +.. literalinclude:: Step3/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CXX_STANDARD-variable-remove + :language: cmake + :start-after: # specify the C++ standard + :end-before: # configure a header file + +Next, we need to create an interface library, ``tutorial_compiler_flags``. And +then use :command:`target_compile_features` to add the compiler feature +``cxx_std_11``. + + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. literalinclude:: Step4/CMakeLists.txt + :caption: TODO 4: CMakeLists.txt + :name: CMakeLists.txt-cxx_std-feature + :language: cmake + :start-after: # specify the C++ standard + :end-before: # TODO 2: Create helper + +.. raw:: html + + </details> + +Finally, with our interface library set up, we need to link our +executable ``Target``, our ``MathFunctions`` library, and our ``SqrtLibrary`` +library to our new +``tutorial_compiler_flags`` library. Respectively, the code will look like +this: + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> + +.. literalinclude:: Step4/CMakeLists.txt + :caption: TODO 5: CMakeLists.txt + :name: CMakeLists.txt-target_link_libraries-step4 + :language: cmake + :start-after: add_executable(Tutorial tutorial.cxx) + :end-before: # add the binary tree to the search path for include file + +.. raw:: html + + </details> + +this: + +.. raw:: html + + <details><summary>TODO 6: Click to show/hide answer</summary> + +.. literalinclude:: Step4/MathFunctions/CMakeLists.txt + :caption: TODO 6: MathFunctions/CMakeLists.txt + :name: MathFunctions-CMakeLists.txt-target_link_libraries-step4 + :language: cmake + :start-after: # link our compiler flags interface library + :end-before: target_link_libraries(MathFunctions + +.. raw:: html + + </details> + +and this: + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> + +.. literalinclude:: Step4/MathFunctions/CMakeLists.txt + :caption: TODO 7: MathFunctions/CMakeLists.txt + :name: MathFunctions-SqrtLibrary-target_link_libraries-step4 + :language: cmake + :start-after: target_link_libraries(SqrtLibrary + :end-before: endif() + +.. raw:: html + + </details> + + +With this, all of our code still requires C++ 11 to build. Notice +though that with this method, it gives us the ability to be specific about +which targets get specific requirements. In addition, we create a single +source of truth in our interface library. diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst index d606f30..694dfaf 100644 --- a/Help/guide/tutorial/Adding a Library.rst +++ b/Help/guide/tutorial/Adding a Library.rst @@ -409,7 +409,7 @@ that has sources ``mysqrt.cxx``. :name: MathFunctions/CMakeLists.txt-add_library-SqrtLibrary :language: cmake :start-after: # library that just does sqrt - :end-before: target_link_libraries(MathFunctions + :end-before: # TODO 7: Link .. raw:: html @@ -426,7 +426,8 @@ enabled. :caption: TODO 13 : MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-target_link_libraries-SqrtLibrary :language: cmake - :lines: 16-18 + :start-after: to tutorial_compiler_flags + :end-before: endif() .. raw:: html diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt index f051826..ac3e9f1 100644 --- a/Help/guide/tutorial/Step3/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/CMakeLists.txt @@ -3,6 +3,12 @@ cmake_minimum_required(VERSION 3.10) # set the project name and version project(Tutorial VERSION 1.0) +# TODO 4: Replace the following code by: +# * Creating an interface library called tutorial_compiler_flags +# Hint: use add_library() with the INTERFACE signature +# * Add compiler feature cxx_std_11 to tutorial_compiler_flags +# Hint: Use target_compile_features() + # specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) @@ -20,6 +26,8 @@ list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") # add the executable add_executable(Tutorial tutorial.cxx) +# TODO 5: Link Tutorial to tutorial_compiler_flags + target_link_libraries(Tutorial PUBLIC MathFunctions) # TODO 3: Remove use of EXTRA_INCLUDES diff --git a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt index 6f86ffe..0ffb9e1 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt @@ -14,5 +14,9 @@ if (USE_MYMATH) mysqrt.cxx ) + # TODO 7: Link SqrtLibrary to tutorial_compiler_flags + target_link_libraries(MathFunctions PUBLIC SqrtLibrary) endif() + +# TODO 6: Link MathFunctions to tutorial_compiler_flags diff --git a/Help/guide/tutorial/Step4/CMakeLists.txt b/Help/guide/tutorial/Step4/CMakeLists.txt index 7531fb4..fba9766 100644 --- a/Help/guide/tutorial/Step4/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/CMakeLists.txt @@ -1,33 +1,27 @@ -# TODO 5: Update the minimum required version to 3.15 +# TODO 1: Update the minimum required version to 3.15 cmake_minimum_required(VERSION 3.10) # set the project name and version project(Tutorial VERSION 1.0) -# TODO 1: Replace the following code by: -# * Creating an interface library called tutorial_compiler_flags -# Hint: use add_library() with the INTERFACE signature -# * Add compiler feature cxx_std_11 to tutorial_compiler_flags -# Hint: Use target_compile_features() - # specify the C++ standard -set(CMAKE_CXX_STANDARD 11) -set(CMAKE_CXX_STANDARD_REQUIRED True) +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) -# TODO 6: Create helper variables to determine which compiler we are using: +# TODO 2: Create helper variables to determine which compiler we are using: # * Create a new variable gcc_like_cxx that is true if we are using CXX and # any of the following compilers: ARMClang, AppleClang, Clang, GNU, LCC # * Create a new variable msvc_cxx that is true if we are using CXX and MSVC # Hint: Use set() and COMPILE_LANG_AND_ID -# TODO 7: Add warning flag compile options to the interface library +# TODO 3: Add warning flag compile options to the interface library # tutorial_compiler_flags. # * For gcc_like_cxx, add flags -Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused # * For msvc_cxx, add flags -W3 # Hint: Use target_compile_options() -# TODO 8: With nested generator expressions, only use the flags for the +# TODO 4: With nested generator expressions, only use the flags for the # build-tree # Hint: Use BUILD_INTERFACE @@ -41,9 +35,7 @@ add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -# TODO 2: Link to tutorial_compiler_flags - -target_link_libraries(Tutorial PUBLIC MathFunctions) +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt index ffab4f0..48561eb 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt @@ -17,9 +17,10 @@ if (USE_MYMATH) mysqrt.cxx ) - # TODO 4: Link to tutorial_compiler_flags - + # link our compiler flags interface library + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC SqrtLibrary) endif() -# TODO 3: Link to tutorial_compiler_flags +# link our compiler flags interface library +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst index ade9149..abb291b 100644 --- a/Help/manual/cpack-generators.7.rst +++ b/Help/manual/cpack-generators.7.rst @@ -20,6 +20,7 @@ Generators /cpack_gen/dmg /cpack_gen/external /cpack_gen/freebsd + /cpack_gen/innosetup /cpack_gen/ifw /cpack_gen/nsis /cpack_gen/nuget diff --git a/Help/release/dev/cpack-innosetup.rst b/Help/release/dev/cpack-innosetup.rst new file mode 100644 index 0000000..a9f8e8e --- /dev/null +++ b/Help/release/dev/cpack-innosetup.rst @@ -0,0 +1,12 @@ +cpack-innosetup +--------------- + +* The :cpack_gen:`CPack Inno Setup Generator` was added to package using + Inno Setup. + + The new generator adds: + + * A lot of options to customize the Inno Setup installer (e.g. custom + installation rules) + * Start menu and desktop shortcuts + * Components (and also downloaded components) diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 3b27fc3..5eb86c6 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -9,7 +9,7 @@ include: =============================== =============================================== Value Name =============================== =============================================== -``Absoft`` `Absoft Fortran`_ +``Absoft`` Absoft Fortran ``ADSP`` Analog VisualDSP++ ``AppleClang`` Apple Clang ``ARMCC`` ARM Compiler @@ -50,7 +50,6 @@ Value Name This variable is not guaranteed to be defined for all compilers or languages. -.. _Absoft Fortran: https://www.absoft.com .. _LLVM Clang: https://clang.llvm.org .. _Embarcadero: https://www.embarcadero.com .. _Classic Flang Fortran Compiler: https://github.com/flang-compiler/flang |