From 95390910848d6022d8e606c2db3b408cc2fe3b24 Mon Sep 17 00:00:00 2001 From: Andrii Doroshenko Date: Tue, 26 May 2020 15:23:15 +0300 Subject: [PATCH] Document `custom_modules` build option (#3595) * Document `custom_modules` build option --- .../introduction_to_the_buildsystem.rst | 32 ++++++++- development/cpp/custom_modules_in_cpp.rst | 69 ++++++++++++++++--- 2 files changed, 91 insertions(+), 10 deletions(-) diff --git a/development/compiling/introduction_to_the_buildsystem.rst b/development/compiling/introduction_to_the_buildsystem.rst index b7f893209..28e6c5b88 100644 --- a/development/compiling/introduction_to_the_buildsystem.rst +++ b/development/compiling/introduction_to_the_buildsystem.rst @@ -182,6 +182,36 @@ This flag appends ``.32`` or ``.64`` suffixes to resulting binaries when relevant. If ``bits=default`` is used, the suffix will match the detected architecture. +.. _doc_buildsystem_custom_modules: + +Custom modules +-------------- + +It's possible to compile modules residing outside of Godot's directory +tree, along with the built-in modules. + +A ``custom_modules`` build option can be passed to the command line before +compiling. The option represents a comma-separated list of directory paths +containing a collection of independent C++ modules that can be seen as C++ +packages, just like the built-in ``modules/`` directory. + +For instance, it's possible to provide both relative, absolute, and user +directory paths containing such modules: + +:: + + scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules" + +.. note:: + + If there's any custom module with the exact directory name as a built-in + module, the engine will only compile the custom one. This logic can be used + to override built-in module implementations. + +.. seealso:: + + :ref:`doc_custom_modules_in_c++` + Other build options ------------------- @@ -206,7 +236,7 @@ source to initialize any SCons build options passed via the command line: .. code-block:: python # custom.py - + optimize = "size" module_mono_enabled = "yes" use_llvm = "yes" diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst index bd187d8c6..470c9334c 100644 --- a/development/cpp/custom_modules_in_cpp.rst +++ b/development/cpp/custom_modules_in_cpp.rst @@ -257,6 +257,57 @@ The output will be ``60``. template. See the :ref:`Compiling ` pages for more information. +Compiling a module externally +----------------------------- + +Compiling a module involves moving the module's sources directly under the +engine's ``modules/`` directory. While this is the most straightforward way to +compile a module, there are a couple of reasons as to why this might not be a +practical thing to do: + +1. Having to manually copy modules sources every time you want to compile the + engine with or without the module, or taking additional steps needed to + manually disable a module during compilation with a build option similar to + ``module_summator_enabled=no``. Creating symbolic links may also be a solution, + but you may additionally need to overcome OS restrictions like needing the + symbolic link privilege if doing this via script. + +2. Depending on whether you have to work with the engine's source code, the + module files added directly to ``modules/`` changes the working tree to the + point where using a VCS (like ``git``) proves to be cumbersome as you need to + make sure that only the engine-related code is committed by filtering + changes. + +So if you feel like the independent structure of custom modules is needed, lets +take our "summator" module and move it to the engine's parent directory: + +.. code-block:: shell + + mkdir ../modules + mv modules/summator ../modules + +Compile the engine with our module by providing ``custom_modules`` build option +which accepts a comma-separated list of directory paths containing custom C++ +modules, similar to the following: + +.. code-block:: shell + + scons custom_modules=../modules + +The build system shall detect all modules under the ``../modules`` directory +and compile them accordingly, including our "summator" module. + +.. warning:: + + Any path passed to ``custom_modules`` will be converted to an absolute path + internally as a way to distinguish between custom and built-in modules. It + means that things like generating module documentation may rely on a + specific path structure on your machine. + +.. seealso:: + + :ref:`Introduction to the buildsystem - Custom modules build option `. + Customizing module types initialization --------------------------------------- @@ -462,14 +513,14 @@ There are several steps in order to setup custom docs for the module: ] The ``get_doc_path()`` function is used by the build system to determine -the location of the docs. In this case, they will be located in the +the location of the docs. In this case, they will be located in the ``modules/summator/doc_classes`` directory. If you don't define this, -the doc path for your module will fall back to the main ``doc/classes`` +the doc path for your module will fall back to the main ``doc/classes`` directory. The ``get_doc_classes()`` method is necessary for the build system to -know which registered classes belong to the module. You need to list all of your -classes here. The classes that you don't list will end up in the +know which registered classes belong to the module. You need to list all of your +classes here. The classes that you don't list will end up in the main ``doc/classes`` directory. .. tip:: @@ -483,13 +534,13 @@ main ``doc/classes`` directory. Untracked files: (use "git add ..." to include in what will be committed) - + doc/classes/MyClass2D.xml doc/classes/MyClass4D.xml doc/classes/MyClass5D.xml doc/classes/MyClass6D.xml ... - + 3. Now we can generate the documentation: @@ -505,13 +556,13 @@ Run command: user@host:~/godot/bin$ ./bin/ --doctool . -Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see +Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see that it contains a ``Summator.xml`` file, or any other classes, that you referenced in your ``get_doc_classes`` function. Edit the file(s) following :ref:`doc_updating_the_class_reference` and recompile the engine. -Once the compilation process is finished, the docs will become accessible within +Once the compilation process is finished, the docs will become accessible within the engine's built-in documentation system. In order to keep documentation up-to-date, all you'll have to do is simply modify @@ -519,7 +570,7 @@ one of the XML files and recompile the engine from now on. If you change your module's API, you can also re-extract the docs, they will contain the things that you previously added. Of course if you point it to your godot -folder, make sure you don't lose work by extracting older docs from an older engine build +folder, make sure you don't lose work by extracting older docs from an older engine build on top of the newer ones. Note that if you don't have write access rights to your supplied ````,