mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-03 05:48:42 +03:00
Merge branch 'master' into 3.2
This commit is contained in:
Rémi Verschelde
@@ -8,12 +8,19 @@ Android Studio
|
||||
It has a feature-rich editor which supports Java and C/C++. It can be used to
|
||||
work on Godot's core engine as well as the Android platform codebase.
|
||||
|
||||
- From Android Studio's welcome window, select
|
||||
**Open an existing Android Studio project**.
|
||||
Importing the project
|
||||
---------------------
|
||||
|
||||
.. image:: img/android_studio_setup_project_1.png
|
||||
- From the Android Studio's welcome window select **Open an existing
|
||||
Android Studio project**.
|
||||
|
||||
- Navigate to ``<Godot root directory>/platform/android/java`` and select the ``settings.gradle`` gradle file.
|
||||
.. figure:: img/android_studio_setup_project_1.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
Android Studio's welcome window.
|
||||
|
||||
- Navigate to ``<Godot root directory>/platform/android/java`` and select the ``settings.gradle`` file.
|
||||
- Android Studio will import and index the project.
|
||||
- To build the project, follow the :ref:`compiling instructions <toc-devel-compiling>`.
|
||||
|
||||
|
||||
@@ -3,29 +3,39 @@
|
||||
CLion
|
||||
=====
|
||||
|
||||
`CLion <https://www.jetbrains.com/clion/>`_ is a commercial IDE for C++.
|
||||
It requires a ``CMakeLists.txt`` file as a project file, which is problematic
|
||||
for Godot which uses the SCons buildsystem instead of CMake.
|
||||
However, there is a ``CMakeLists.txt`` configuration for
|
||||
:ref:`Android Studio <doc_configuring_an_ide_android_studio>` which can also
|
||||
be used by CLion.
|
||||
`CLion <https://www.jetbrains.com/clion/>`_ is a commercial
|
||||
`JetBrains <https://www.jetbrains.com/>`_ IDE for C++.
|
||||
|
||||
- If you've already opened another project, choose **File > Open** at the top of
|
||||
the CLion window. Otherwise, choose the option to import an existing project
|
||||
in the Welcome window.
|
||||
- Navigate to your Godot Git clone then select the folder
|
||||
``platform/android/java/lib`` - the ``CMakeLists.txt`` file is located there.
|
||||
Select the folder (*not* the ``CMakeLists.txt file``), then click **OK**.
|
||||
Importing the project
|
||||
---------------------
|
||||
|
||||
.. image:: img/clion_1_open.png
|
||||
CLion requires a ``CMakeLists.txt`` file as a project file, which is problematic
|
||||
for Godot because it uses the SCons buildsystem instead of CMake. However,
|
||||
there is a ``CMakeLists.txt`` configuration for :ref:`Android Studio <doc_configuring_an_ide_android_studio>`
|
||||
which can also be used by CLion.
|
||||
|
||||
- From the CLion's welcome window choose the option to import an existing
|
||||
project. If you've already opened another project, choose **File > Open**
|
||||
from the top menu.
|
||||
- Navigate to ``<Godot root directory>/platform/android/java/lib`` (the
|
||||
``CMakeLists.txt`` file is located there) and select it (but *not* the
|
||||
``CMakeLists.txt`` file itself), then click **OK**.
|
||||
|
||||
.. figure:: img/clion_1_open.png
|
||||
:align: center
|
||||
|
||||
The folder containing the ``CMakeLists.txt`` file.
|
||||
|
||||
- If this popup window appears, select **This Window** to open the project:
|
||||
|
||||
.. image:: img/clion_2_this_window.png
|
||||
.. figure:: img/clion_2_this_window.png
|
||||
:align: center
|
||||
|
||||
- Choose **Tools > CMake >Change Project Root** and select the root Godot folder.
|
||||
- Choose **Tools > CMake > Change Project Root** from the top menu and select
|
||||
the Godot root folder.
|
||||
|
||||
.. image:: img/clion_3_change_project_root.png
|
||||
.. figure:: img/clion_3_change_project_root.png
|
||||
:align: center
|
||||
|
||||
- You should be now be able to see all the project files. Autocomplete should
|
||||
work once the project has finished indexing.
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 5.5 KiB After Width: | Height: | Size: 4.6 KiB |
BIN
development/cpp/configuring_an_ide/img/vscode_configure_task.png
Normal file
BIN
development/cpp/configuring_an_ide/img/vscode_configure_task.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 6.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.8 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 7.3 KiB |
@@ -16,8 +16,8 @@ Development Environment), here are setup instructions for some popular ones:
|
||||
clion
|
||||
kdevelop
|
||||
qt_creator
|
||||
visual_studio_code
|
||||
visual_studio
|
||||
visual_studio_code
|
||||
xcode
|
||||
|
||||
It is possible to use other IDEs, but their setup is not documented yet.
|
||||
|
||||
@@ -5,54 +5,83 @@ KDevelop
|
||||
|
||||
`KDevelop <https://www.kdevelop.org>`_ is a free, open source IDE for all desktop platforms.
|
||||
|
||||
Start by opening KDevelop and choosing **Open Project**.
|
||||
Importing the project
|
||||
---------------------
|
||||
|
||||
.. image:: img/kdevelop_newproject.png
|
||||
- From the KDevelop's main screen select **Open Project**.
|
||||
|
||||
Choose the directory where you cloned Godot.
|
||||
.. figure:: img/kdevelop_newproject.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
On the next screen, choose **Custom Build System** for the **Project Manager**.
|
||||
KDevelop's main screen.
|
||||
|
||||
.. image:: img/kdevelop_custombuild.png
|
||||
- Navigate to the Godot root folder and select it.
|
||||
- On the next screen, choose **Custom Build System** for the **Project Manager**.
|
||||
|
||||
Now that the project has been imported, open the project configuration.
|
||||
.. figure:: img/kdevelop_custombuild.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
.. image:: img/kdevelop_openconfig.png
|
||||
- After the project has been imported, open the project configuration by right-clicking
|
||||
on it in the **Projects** panel and selecting **Open Configuration..** option.
|
||||
|
||||
Add the following includes/imports:
|
||||
.. figure:: img/kdevelop_openconfig.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
.. code-block:: none
|
||||
- Under **Language Support** open the **Includes/Imports** tab and add the following paths:
|
||||
|
||||
. // a dot to indicate the root of the Godot project
|
||||
core/
|
||||
core/os/
|
||||
core/math/
|
||||
drivers/
|
||||
platform/linuxbsd/ // make that platform/osx/ if you're using macOS
|
||||
.. code-block:: none
|
||||
|
||||
.. image:: img/kdevelop_addincludes.png
|
||||
. // A dot, to indicate the root of the Godot project
|
||||
core/
|
||||
core/os/
|
||||
core/math/
|
||||
drivers/
|
||||
platform/<your_platform>/ // Replace <your_platform> with a folder
|
||||
corresponding to your current platform
|
||||
|
||||
Apply the changes.
|
||||
.. figure:: img/kdevelop_addincludes.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
Switch to the **Custom Build System** tab. Add a build configuration
|
||||
and keep the build directory blank. Enable build tools and add ``scons``
|
||||
as the executable then add ``platform=linuxbsd target=debug`` (``platform=osx``
|
||||
if you're on macOS) as the arguments.
|
||||
- Apply the changes.
|
||||
- Under **Custom Build System** add a new build configuration with the following settings:
|
||||
|
||||
.. image:: img/kdevelop_buildconfig.png
|
||||
+-----------------+------------------------------------------------------------------------------+
|
||||
| Build Directory | *blank* |
|
||||
+-----------------+------------------------------------------------------------------------------+
|
||||
| Enable | **True** |
|
||||
+-----------------+------------------------------------------------------------------------------+
|
||||
| Executable | **scons** |
|
||||
+-----------------+------------------------------------------------------------------------------+
|
||||
| Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. |
|
||||
+-----------------+------------------------------------------------------------------------------+
|
||||
|
||||
Next, we need to tell KDevelop where to find the binary.
|
||||
From the **Run** menu, choose **Configure Launches**.
|
||||
.. figure:: img/kdevelop_buildconfig.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
.. image:: img/kdevelop_configlaunches.png
|
||||
- Apply the changes and close the configuration window.
|
||||
|
||||
Click **Add** if no launcher exists. Then add the path to your
|
||||
executable in the executable section. Your executable should be located
|
||||
in the ``bin/`` subdirectory and should be named something like
|
||||
``godot.linuxbsd.tools.64`` (the name could be different depending on your
|
||||
platform and build options).
|
||||
Debugging the project
|
||||
---------------------
|
||||
|
||||
.. image:: img/kdevelop_configlaunches2.png
|
||||
- Select **Run > Configure Launches...** from the top menu.
|
||||
|
||||
.. figure:: img/kdevelop_configlaunches.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Click **Add** to create a new launch configuration.
|
||||
- Select **Executable** option and specify the path to your executable located in
|
||||
the ``<Godot root directory>/bin`` folder. The name depends on your build configuration,
|
||||
e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled.
|
||||
|
||||
.. figure:: img/kdevelop_configlaunches2.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
If you run into any issues, ask for help in one of
|
||||
`Godot's community channels <https://godotengine.org/community>`__.
|
||||
|
||||
@@ -3,103 +3,109 @@
|
||||
Qt Creator
|
||||
==========
|
||||
|
||||
Qt Creator is a free, open source IDE for all desktop platforms.
|
||||
`Qt Creator <https://doc.qt.io/qtcreator/index.html>`_ is a free, open source IDE for all desktop platforms.
|
||||
|
||||
Importing the project
|
||||
---------------------
|
||||
|
||||
- Choose **New Project > Import Project > Import Existing Project**.
|
||||
- From the Qt Creator's main screen select **New Project > Import Project > Import Existing Project**.
|
||||
|
||||
.. image:: img/qtcreator-new-project.png
|
||||
.. figure:: img/qtcreator-new-project.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Set the path to your Godot root directory and enter the project name.
|
||||
- Under **Location** select the Godot root folder.
|
||||
|
||||
.. image:: img/qtcreator-set-project-path.png
|
||||
.. figure:: img/qtcreator-set-project-path.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Here you can choose which folders and files will be visible to the project.
|
||||
C/C++ files are added automatically. Potentially useful additions:
|
||||
- Next, you can choose which folders and files will be visible to the project.
|
||||
While C/C++ files are added automatically, other extensions can be potentially useful:
|
||||
``*.py`` for buildsystem files, ``*.java`` for Android platform development,
|
||||
``*.mm`` for macOS platform development. Click **Next**.
|
||||
``*.mm`` for macOS platform development.
|
||||
|
||||
.. image:: img/qtcreator-apply-import-filter.png
|
||||
.. figure:: img/qtcreator-apply-import-filter.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Click **Finish**.
|
||||
- Add a line containing ``.`` to ``project_name.includes`` to get working
|
||||
code completion.
|
||||
.. note:: You can change this configuration later by right-clicking on your project
|
||||
and selecting the **Edit Files...** option.
|
||||
|
||||
.. image:: img/qtcreator-project-name-includes.png
|
||||
.. figure:: img/qtcreator-edit-files-menu.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
Build and run
|
||||
--------------
|
||||
|
||||
Build configuration:
|
||||
- Finish the import.
|
||||
- Open the ``project_name.includes`` file and add a line containing ``.`` to it
|
||||
to correctly enable the code completion.
|
||||
|
||||
- Click on **Projects** and open the **Build** tab.
|
||||
.. figure:: img/qtcreator-project-name-includes.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- From the left-side menu select **Projects** and open the **Build** tab.
|
||||
- Delete the predefined ``make`` build step.
|
||||
|
||||
.. image:: img/qtcreator-projects-build.png
|
||||
.. figure:: img/qtcreator-projects-build.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Click **Add Build Step > Custom Process Step**.
|
||||
- Click **Add Build Step > Custom Process Step** to add a new build step
|
||||
with the following settings:
|
||||
|
||||
.. image:: img/qtcreator-add-custom-process-step.png
|
||||
+-----------+------------------------------------------------------------------------------+
|
||||
| Command | **scons** |
|
||||
+-----------+------------------------------------------------------------------------------+
|
||||
| Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. |
|
||||
+-----------+------------------------------------------------------------------------------+
|
||||
|
||||
- Type ``scons`` in the **Command** field. If it fails with
|
||||
``Could not start process "scons"``, it can mean that ``scons`` is not in
|
||||
your ``PATH`` environment variable. In this case, you'll have to specify the
|
||||
full path to the SCons binary.
|
||||
- Fill the **Arguments** field with your compilation options
|
||||
(e.g.: ``p=linuxbsd target=debug -j 4``).
|
||||
.. figure:: img/qtcreator-set-scons-command.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
.. image:: img/qtcreator-set-scons-command.png
|
||||
.. note:: If the build fails with ``Could not start process "scons"``, it can mean that ``scons``
|
||||
is not in your ``PATH`` environment variable. In this case, you'll have to specify the
|
||||
full path to the SCons binary.
|
||||
|
||||
Run configuration:
|
||||
Debugging the project
|
||||
---------------------
|
||||
|
||||
- Open the **Run** tab.
|
||||
- Point the **Executable** to your compiled Godot binary
|
||||
(e.g: ``%{buildDir}/bin/godot.linuxbsd.opt.tools.64``).
|
||||
- If you want to run a specific project, point **Working directory** to the
|
||||
project folder.
|
||||
- If you want to run the editor, add ``-e`` to the **Command line arguments**
|
||||
field.
|
||||
- From the left-side menu select **Projects** and open the **Run** tab.
|
||||
- Under **Executable** specify the path to your executable located in
|
||||
the ``<Godot root directory>/bin`` folder. The name depends on your build configuration,
|
||||
e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled.
|
||||
You can use ``%{buildDir}`` to reference the project root, e.g: ``%{buildDir}/bin/godot.x11.opt.tools.64``.
|
||||
- If you want to run a specific project, specify its root folder under **Working directory**.
|
||||
- If you want to run the editor, add ``-e`` to the **Command line arguments** field.
|
||||
|
||||
.. image:: img/qtcreator-run-command.png
|
||||
.. figure:: img/qtcreator-run-command.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
Updating sources after pulling latest commits
|
||||
---------------------------------------------
|
||||
|
||||
As a developer, you usually want to frequently pull the latest commits from the
|
||||
upstream Git repository or a specific fork. However, this brings a problem with
|
||||
it: as the development continues, source files (and folders) are added or
|
||||
removed. These changes need to be reflected in your project files for Qt Creator
|
||||
too, so you continue to have a nice programming experience. A simple way to
|
||||
check is to right click at your root folder in the **Projects View** and click
|
||||
on **Edit files...**.
|
||||
|
||||
.. image:: img/qtcreator-edit-files-menu.png
|
||||
|
||||
Now a new dialog should appear that is similar in functionality to the one in
|
||||
the third step of the *Importing the project* section above. Here, you can check
|
||||
whether you want to add/remove specific files and/or folders. You can choose by
|
||||
clicking with your mouse or just simply by clicking the **Apply Filter** button.
|
||||
Click on **OK** and you're ready to continue working.
|
||||
|
||||
.. image:: img/qtcreator-edit-files-dialog.png
|
||||
To learn more about command line arguments, refer to the
|
||||
:ref:`command line tutorial <doc_command_line_tutorial>`.
|
||||
|
||||
Code style configuration
|
||||
------------------------
|
||||
|
||||
Developers must follow the project's :ref:`code style <doc_code_style_guidelines>`
|
||||
and the IDE should help them follow it. By default, Qt Creator does use spaces
|
||||
and the IDE should help them follow it. By default, Qt Creator uses spaces
|
||||
for indentation which doesn't match the Godot code style guidelines. You can
|
||||
change this behavior by changing the **Code Style** in **Options > C++**.
|
||||
|
||||
.. image:: img/qtcreator-options-cpp.png
|
||||
.. figure:: img/qtcreator-options-cpp.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
Click on **Edit** to change the current settings, then click on
|
||||
**Copy Built-in Code Style** button to set a new code style. Set a name for it
|
||||
(e.g. Godot) and change the Tab policy to be **Tabs Only**.
|
||||
|
||||
.. image:: img/qtcreator-edit-codestyle.png
|
||||
.. figure:: img/qtcreator-edit-codestyle.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
If you run into any issues, ask for help in one of
|
||||
`Godot's community channels <https://godotengine.org/community>`__.
|
||||
|
||||
@@ -3,62 +3,66 @@
|
||||
Visual Studio
|
||||
=============
|
||||
|
||||
Visual Studio Community is a Windows-only IDE that's free for non-commercial use.
|
||||
`Visual Studio Community <https://visualstudio.microsoft.com>`__ is a Windows-only IDE
|
||||
by `Microsoft <https://microsoft.com>`_ that's free for non-commercial use.
|
||||
It has many useful features, such as memory view, performance view, source
|
||||
control and more. You can get it
|
||||
`from Microsoft <https://visualstudio.microsoft.com/downloads/>`__.
|
||||
control and more.
|
||||
|
||||
Setup
|
||||
-----
|
||||
Importing the project
|
||||
---------------------
|
||||
|
||||
To start developing with Visual Studio, follow these steps:
|
||||
Visual Studio requires a solution file to work on a project. While Godot does not come
|
||||
with the solution file, it can be generated using SCons.
|
||||
|
||||
- Open the Visual Studio Installer and install the C++ package:
|
||||
- Navigate to the Godot root folder and open a Command Prompt or PowerShell window.
|
||||
- Run ``scons platform=windows vsproj=yes`` to generate the solution.
|
||||
- You can now open the project by double-clicking on the ``godot.sln`` in the project root
|
||||
or by using the **Open a project or solution** option inside of the Visual Studio.
|
||||
- Use the **Build** top menu to build the project.
|
||||
|
||||
.. image:: img/vs_1_install_cpp_package.png
|
||||
.. warning:: Visual Studio must be configured with the C++ package. It can be selected
|
||||
in the intaller:
|
||||
|
||||
- Open a Command Prompt or PowerShell window, use ``cd`` to reach the Godot source
|
||||
directory and run ``scons platform=windows vsproj=yes``.
|
||||
.. figure:: img/vs_1_install_cpp_package.png
|
||||
:align: center
|
||||
|
||||
- Now open the Godot folder by clicking **Open a project or solution** and choose
|
||||
``godot.sln``.
|
||||
- You can also double-click the ``godot.sln`` file in Explorer.
|
||||
|
||||
You can now start developing with Visual Studio.
|
||||
|
||||
Debugging
|
||||
---------
|
||||
Debugging the project
|
||||
---------------------
|
||||
|
||||
Visual Studio features a powerful debugger. This allows the user to examine Godot's
|
||||
source code, stop at specific points in the code, make changes, and view them on the run.
|
||||
source code, stop at specific points in the code, inspect the current execution context,
|
||||
and make live changes to the codebase.
|
||||
|
||||
.. note:: Debugging the Godot Engine inside the editor will require an extra setup step.
|
||||
You can launch the project with the debugger attached using the **Debug > Start Debugging**
|
||||
option from the top menu. However, unless you want to debug the project manager specifically,
|
||||
you'd need to configure debugging options first. This is due to the fact that when the Godot
|
||||
project manager opens a project, the initial process is terminated and the debugger gets detached.
|
||||
|
||||
Because opening Godot opens the Project Manager at first instead of the project
|
||||
you're working on, the debugger will detach as soon as you open a project.
|
||||
This means that the debugger will stop, even though Godot is still running in
|
||||
another process.
|
||||
- To configure the launch options to use with the debugger use **Project > Properties**
|
||||
from the top menu:
|
||||
|
||||
To overcome this, you need to edit the debugging command line arguments in VS. In your
|
||||
project, click **Project > Project Properties**:
|
||||
.. figure:: img/vs_2_project_properties.png
|
||||
:align: center
|
||||
|
||||
.. image:: img/vs_2_project_properties.png
|
||||
- Open the **Debugging** section and under **Command Arguments** add two new arguments:
|
||||
the ``-e`` flag opens the editor instead of the project manager, and the ``--path`` argument
|
||||
tells the executable to open the specified project (must be provided as an *absolute* path
|
||||
to the project root, not the ``project.godot`` file).
|
||||
|
||||
Then add this to the command arguments:
|
||||
|
||||
.. image:: img/vs_3_debug_command_line.png
|
||||
|
||||
- The ``-e`` flag is for entering the editor directly (which skips the Project Manager).
|
||||
- The ``--path`` argument should be an *absolute* path to a project directory (not a
|
||||
`project.godot` file).
|
||||
.. figure:: img/vs_3_debug_command_line.png
|
||||
:align: center
|
||||
|
||||
To learn more about command line arguments, refer to the
|
||||
:ref:`command line tutorial <doc_command_line_tutorial>`.
|
||||
|
||||
To check that everything is working, put a breakpoint in ``main.cpp`` and press F5 to
|
||||
Even if you start the project without a debugger attached it can still be connected to the running
|
||||
process using **Debug > Attach to Process...** menu.
|
||||
|
||||
To check that everything is working, put a breakpoint in ``main.cpp`` and press :kbd:`F5` to
|
||||
start debugging.
|
||||
|
||||
.. image:: img/vs_4_debugging_main.png
|
||||
.. figure:: img/vs_4_debugging_main.png
|
||||
:align: center
|
||||
|
||||
If you run into any issues, ask for help in one of
|
||||
`Godot's community channels <https://godotengine.org/community>`__.
|
||||
|
||||
@@ -3,47 +3,104 @@
|
||||
Visual Studio Code
|
||||
==================
|
||||
|
||||
Visual Studio Code is a free cross-platform IDE (not to be confused with
|
||||
:ref:`doc_configuring_an_ide_vs`). You can get it
|
||||
`from Microsoft <https://code.visualstudio.com/>`__.
|
||||
`Visual Studio Code <https://code.visualstudio.com>`_ is a free cross-platform IDE
|
||||
by `Microsoft <https://microsoft.com>`_ (not to be confused with :ref:`doc_configuring_an_ide_vs`).
|
||||
|
||||
Importing the project
|
||||
---------------------
|
||||
|
||||
- Make sure the C/C++ extension is installed. You can find instructions in
|
||||
the `documentation <https://code.visualstudio.com/docs/languages/cpp>`_.
|
||||
- Open the cloned Godot folder in Visual Studio Code with
|
||||
the `official documentation <https://code.visualstudio.com/docs/languages/cpp>`_.
|
||||
- From the Visual Studio Code's main screen open the Godot root folder with
|
||||
**File > Open Folder...**.
|
||||
- Press :kbd:`Ctrl + Shift + P` to open the command prompt window and enter *Configure Task*.
|
||||
|
||||
In order to build the project, you need two configuration files:
|
||||
``launch.json`` and ``tasks.json``. To create them:
|
||||
.. figure:: img/vscode_configure_task.png
|
||||
:align: center
|
||||
|
||||
- Open the **Debug** view by pressing :kbd:`Ctrl + Shift + D` and select the
|
||||
cogwheel with an orange dot:
|
||||
- Select the **Create tasks.json file from template** option.
|
||||
|
||||
.. image:: img/vscode_1_create_launch.json.png
|
||||
.. figure:: img/vscode_create_tasksjson.png
|
||||
:align: center
|
||||
|
||||
- Select **C++ (GDB/LLDB)** (it might be named differently on macOS or Windows).
|
||||
- Then select **Others**.
|
||||
|
||||
- Update ``launch.json`` to match:
|
||||
.. figure:: img/vscode_create_tasksjson_others.png
|
||||
:align: center
|
||||
|
||||
.. image:: img/vscode_2_launch.json.png
|
||||
- Within the ``tasks.json`` file find the ``"tasks"`` array and add a new section to it:
|
||||
|
||||
If you're following this guide on macOS or Windows, you will have to adjust
|
||||
``godot.linuxbsd.tools.64`` accordingly.
|
||||
.. code-block:: js
|
||||
|
||||
- Create a ``tasks.json`` file by starting the Debug process with :kbd:`F5`.
|
||||
Visual Studio Code will show a dialog with a **Configure Task** button.
|
||||
Choose it and select **Create tasks.json file from template**, then select **Others**.
|
||||
{
|
||||
"label": "build",
|
||||
"type": "shell",
|
||||
"command": "scons",
|
||||
"group": "build",
|
||||
"args": [
|
||||
"platform=x11", // Change to your current platform
|
||||
"target=debug",
|
||||
"-j4"
|
||||
],
|
||||
"problemMatcher": "$msCompile"
|
||||
}
|
||||
|
||||
- Update ``tasks.json`` to match:
|
||||
.. figure:: img/vscode_3_tasks.json.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
.. image:: img/vscode_3_tasks.json.png
|
||||
An example of a filled out ``tasks.json``.
|
||||
|
||||
If you're following this guide on macOS or Windows, you will have to adjust
|
||||
``platform=linuxbsd`` accordingly.
|
||||
Arguments are can be different based on your own setup and needs. See
|
||||
:ref:`doc_introduction_to_the_buildsystem` for a full list of arguments.
|
||||
|
||||
- You can now start the Debug process again to test that everything works.
|
||||
- If the build phase fails, check the console for hints. On Linux, it's most
|
||||
likely due to missing dependencies. Check :ref:`doc_compiling_for_linuxbsd`.
|
||||
Debugging the project
|
||||
---------------------
|
||||
|
||||
To run and debug the project you need to create a new configuration in the ``launch.json`` file.
|
||||
|
||||
- Press :kbd:`Ctrl + Shift + D` to open the Run panel.
|
||||
- If ``launch.json`` file is missing you will be prompted to create a new one.
|
||||
|
||||
.. figure:: img/vscode_1_create_launch.json.png
|
||||
:align: center
|
||||
|
||||
- Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected,
|
||||
adjust the configuration example provided accordingly.
|
||||
- Within the ``launch.json`` file find the ``"configurations"`` array and add a new section to it:
|
||||
|
||||
.. code-block:: js
|
||||
|
||||
{
|
||||
"name": "Launch",
|
||||
"type": "cppdbg",
|
||||
"request": "launch",
|
||||
"program": "${workspaceFolder}/bin/godot.x11.tools.64",
|
||||
// Change to your current platform
|
||||
"args": [ "-e" ],
|
||||
"stopAtEntry": false,
|
||||
"cwd": "${workspaceFolder}",
|
||||
"environment": [],
|
||||
"externalConsole": true,
|
||||
"MIMode": "gdb",
|
||||
"setupCommands": [
|
||||
{
|
||||
"description": "Enable pretty-printing for gdb",
|
||||
"text": "-enable-pretty-printing",
|
||||
"ignoreFailures": true
|
||||
}
|
||||
],
|
||||
"preLaunchTask": "build"
|
||||
}
|
||||
|
||||
.. figure:: img/vscode_2_launch.json.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
An example of a filled out ``launch.json``.
|
||||
|
||||
The name under ``program`` depends on your build configuration,
|
||||
e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled.
|
||||
|
||||
If you run into any issues, ask for help in one of
|
||||
`Godot's community channels <https://godotengine.org/community>`__.
|
||||
|
||||
@@ -3,93 +3,108 @@
|
||||
Xcode
|
||||
=====
|
||||
|
||||
Xcode is a free macOS-only IDE. You can download it from the Mac App Store.
|
||||
`Xcode <https://developer.apple.com/xcode>`_ is a free macOS-only IDE. You can
|
||||
download it from the Mac App Store.
|
||||
|
||||
Project setup
|
||||
-------------
|
||||
Importing the project
|
||||
---------------------
|
||||
|
||||
- Create an Xcode external build project anywhere.
|
||||
- From Xcode's main screen create a new project using the **Other > External Build System** template.
|
||||
|
||||
.. image:: img/xcode_1_create_external_build_project.png
|
||||
.. figure:: img/xcode_1_create_external_build_project.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
Go to the build target's **Info** tab, then:
|
||||
- Open your build targets from the **Targets** section and select the **Info** tab.
|
||||
- Fill out the form with the following settings:
|
||||
|
||||
- Set **Build Tool** to the full path to SCons.
|
||||
- Set **Arguments** to something like
|
||||
``platform=osx tools=yes bits=64 target=debug``.
|
||||
- Set **Directory** to the path to Godot's source folder.
|
||||
- You may uncheck **Pass build settings in environment**.
|
||||
+------------+------------------------------------------------------------------------------+
|
||||
| Build Tool | A full path to the **scons** executable, e.g. **/usr/local/bin/scons** |
|
||||
+------------+------------------------------------------------------------------------------+
|
||||
| Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. |
|
||||
+------------+------------------------------------------------------------------------------+
|
||||
| Directory | A full path to the Godot root folder |
|
||||
+------------+------------------------------------------------------------------------------+
|
||||
|
||||
.. image:: img/xcode_2_configure_scons.png
|
||||
.. figure:: img/xcode_2_configure_scons.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
Add a Command Line Tool target which will be used for indexing the project:
|
||||
- Add a Command Line Tool target which will be used for indexing the project by
|
||||
choosing **File > New > Target...**.
|
||||
|
||||
- In Xcode's menu, choose **File > New > Target...** and add a new Xcode
|
||||
command line tool target.
|
||||
.. figure:: img/xcode_3_add_new_target.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
.. image:: img/xcode_3_add_new_target.png
|
||||
- Select **OS X > Application > Command Line Tool**.
|
||||
|
||||
.. image:: img/xcode_4_select_command_line_target.png
|
||||
.. figure:: img/xcode_4_select_command_line_target.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Name it something so you know not to compile with this target (e.g. ``GodotXcodeIndex``).
|
||||
- Goto the newly created target's **Build Settings** tab and look for **Header Search Paths**.
|
||||
- Set **Header Search Paths** to the absolute path to Godot's source folder.
|
||||
- Make it recursive by adding two asterisks (``**``) to the end of the path,
|
||||
e.g. ``/Users/me/repos/godot-source/**``.
|
||||
.. note:: Name it something so you know not to compile with this target (e.g. ``GodotXcodeIndex``).
|
||||
|
||||
Add the Godot source to the project:
|
||||
- For this target open the **Build Settings** tab and look for **Header Search Paths**.
|
||||
- Set **Header Search Paths** to the absolute path to the Godot root folder. You need to
|
||||
include subdirectories as well. To achieve that, add two two asterisks (``**``) to the
|
||||
end of the path, e.g. ``/Users/me/repos/godot-source/**``.
|
||||
|
||||
- Drag and drop Godot source into the project file browser.
|
||||
- Add the Godot source to the project by dragging and dropping it into the project file browser.
|
||||
- Uncheck **Create external build system project**.
|
||||
|
||||
.. image:: img/xcode_5_after_add_godot_source_to_project.png
|
||||
.. figure:: img/xcode_5_after_add_godot_source_to_project.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Click **Next**.
|
||||
- Select **Create groups**.
|
||||
- Next select **Create groups** for the **Added folders** option and check *only*
|
||||
your command line indexing target in the **Add to targets** section.
|
||||
|
||||
.. image:: img/xcode_6_after_add_godot_source_to_project_2.png
|
||||
.. figure:: img/xcode_6_after_add_godot_source_to_project_2.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Check *only* your command line indexing target in the
|
||||
**Add to targets** section.
|
||||
- Click finish. Xcode will now index the files. This may take a few minutes.
|
||||
- Xcode will now index the files. This may take a few minutes.
|
||||
- Once Xcode is done indexing, you should have jump-to-definition,
|
||||
autocompletion, and full syntax highlighting.
|
||||
|
||||
Scheme setup
|
||||
------------
|
||||
Debugging the project
|
||||
---------------------
|
||||
|
||||
To enable debugging support, edit the external build target's build scheme:
|
||||
To enable debugging support you need to edit the external build target's build and run schemes.
|
||||
|
||||
- Open the scheme editor of the external build target.
|
||||
- Expand the **Build** menu.
|
||||
- Goto **Post Actions**.
|
||||
- Add a new script run action, select your project in **Provide build settings from**
|
||||
as this allows you to use the``${PROJECT_DIR}`` variable.
|
||||
- Locate the **Build > Post Actions** section.
|
||||
- Add a new script run action
|
||||
- Under **Provide build settings from** select your project. This allows to reference
|
||||
the project directory within the script.
|
||||
- Create a script that will give the binary a name that Xcode can recognize, e.g.:
|
||||
|
||||
.. image:: img/xcode_7_setup_build_post_action.png
|
||||
.. code-block:: shell
|
||||
|
||||
ln -f ${PROJECT_DIR}/godot/bin/godot.osx.tools.64 ${PROJECT_DIR}/godot/bin/godot
|
||||
|
||||
.. figure:: img/xcode_7_setup_build_post_action.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Write a script that gives the binary a name that Xcode will recognize, such as:
|
||||
``ln -f ${PROJECT_DIR}/godot/bin/godot.osx.tools.64 ${PROJECT_DIR}/godot/bin/godot``
|
||||
- Build the external build target.
|
||||
|
||||
Edit the external build target's Run scheme:
|
||||
- Open the scheme editor again and select **Run**.
|
||||
|
||||
- Open the scheme editor again.
|
||||
- Click **Run**.
|
||||
|
||||
.. image:: img/xcode_8_setup_run_scheme.png
|
||||
.. figure:: img/xcode_8_setup_run_scheme.png
|
||||
:figclass: figure-w480
|
||||
:align: center
|
||||
|
||||
- Set the **Executable** to the file you linked in your post-build action script.
|
||||
- Check **Debug executable** if it isn't checked already.
|
||||
- You can go to **Arguments** tab and specify the full path to a
|
||||
``project.godot`` file to debug the editor instead of the project manager.
|
||||
Alternatively, use ``--path`` to point to a project *folder* which will be
|
||||
run directly (instead of opening the editor).
|
||||
- Check **Debug executable**.
|
||||
- You can add two arguments on the **Arguments** tab:
|
||||
the ``-e`` flag opens the editor instead of the project manager, and the ``--path`` argument
|
||||
tells the executable to open the specified project (must be provided as an *absolute* path
|
||||
to the project root, not the ``project.godot`` file).
|
||||
|
||||
Test the Run scheme:
|
||||
|
||||
- Set a breakpoint in ``platform/osx/godot_main_osx.mm``.
|
||||
- If all goes well, it should break at the specified breakpoint.
|
||||
To check that everything is working, put a breakpoint in ``platform/osx/godot_main_osx.mm`` and
|
||||
run the project.
|
||||
|
||||
If you run into any issues, ask for help in one of
|
||||
`Godot's community channels <https://godotengine.org/community>`__.
|
||||
|
||||
@@ -257,6 +257,57 @@ The output will be ``60``.
|
||||
template. See the :ref:`Compiling <toc-devel-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 <doc_buildsystem_custom_modules>`.
|
||||
|
||||
Improving the build system for development
|
||||
------------------------------------------
|
||||
|
||||
@@ -307,11 +358,11 @@ library that will be dynamically loaded when starting our game's binary.
|
||||
Once compiled, we should end up with a ``bin`` directory containing both the
|
||||
``godot*`` binary and our ``libsummator*.so``. However given the .so is not in
|
||||
a standard directory (like ``/usr/lib``), we have to help our binary find it
|
||||
during runtime with the ``LD_LIBRARY_PATH`` environ variable:
|
||||
during runtime with the ``LD_LIBRARY_PATH`` environment variable:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
export LD_LIBRARY_PATH=`pwd`/bin/
|
||||
export LD_LIBRARY_PATH="$PWD/bin/"
|
||||
./bin/godot*
|
||||
|
||||
**note**: Pay attention you have to ``export`` the environ variable otherwise
|
||||
@@ -386,19 +437,19 @@ 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::
|
||||
|
||||
You can use git to check if you have missed some of your classes by checking the
|
||||
You can use Git to check if you have missed some of your classes by checking the
|
||||
untracked files with ``git status``. For example::
|
||||
|
||||
user@host:~/godot$ git status
|
||||
@@ -407,13 +458,13 @@ main ``doc/classes`` directory.
|
||||
|
||||
Untracked files:
|
||||
(use "git add <file>..." 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:
|
||||
|
||||
@@ -429,13 +480,13 @@ Run command:
|
||||
|
||||
user@host:~/godot/bin$ ./bin/<godot_binary> --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
|
||||
@@ -443,7 +494,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 ``<path>``,
|
||||
|
||||
Reference in New Issue
Block a user