.. include:: definitions.rstinc

.. _building-executable-label:

======================
Building an Executable
======================

Building an executable from an Unreal Engine project that uses the AGX Dynamics for Unreal plugin can be done from the Unreal Editor by selecting  ``Top Menu Bar > File > Package Project > <platform>`` and specifying the output directory.
The executable needs a valid license to function, see :ref:`licensing-label` for details.

*****
Linux
*****

Currently only in-project installations of the plugin is supported. See :ref:`install_plugin_in_project-label`.

To use AGX Terrain features in a packaged application copy all ``libvdbgrid`` files from ``<EXPORT_DIRECTORY>/LinuxNoEditor/<PROJECT_NAME>/Plugins/AGXUnreal/Binaries/ThirdParty/agx/lib/Linux/`` to ``<EXPORT_DIRECTORY>/LinuxNoEditor/<PROJECT_NAME>/Binaries/ThirdParty/agx/lib/Linux/``.

*********************************
Automatic Copying of License File
*********************************
During development, it may be convenient to have the AGX Dynamics license file being copied to the target build location automatically during cooked builds for fast testing.
The same is true when using the ``Launch`` button inside the Unreal Editor.

.. warning::
    Care must be taken to ensure AGX Dynamics license files are never distributed! Use the automatic copying described here with care.

This can be achieved in one of two ways:

-  Set environment variable ``AGXUNREAL_COPY_LICENSE_FILE_TO_TARGET`` to ``true``.

-  Set ``bCopyLicenseFileToTarget`` to ``true`` in the ``AGXDynamicsLibrary.Build.cs`` located in ``AGXUnreal/Source/ThirdParty/AGXDynamicsLibrary``.

Note that the automatic copying of the license file is only available for build configurations ``Development``, ``Debug`` and ``DebugGame``.

***********
Limitations
***********
When performing a cooked build of a Blueprint project while having |AGXUnreal| installed as a Project plugin, i.e. |AGXUnreal| is placed directly in ``<PROJECT_NAME>/Plugins``, the |AGXUnreal| resources are not copied to the target location.
The recommended way to solve this is to install the |AGXUnreal| plugin as an Engine plugin, meaning it should be placed in the ``Engine/Plugins/Marketplace`` directory inside your Unreal Engine installation.

***************
Troubleshooting
***************

- | ``WARNING: SafeCopyFile Exception was Exception in mscorlib: Could not find a part of the path <C:/very/long/file/path/...>``

This error message has been observed on Windows while building an executable of an Unreal Editor project using the |AGXUnreal| plugin.
It is caused by a limitation in Windows where paths are not allowed to be longer than a certain limit, often 260 characters.
To circumvent this issue the recommendation is to place the Unreal Editor project closer to the system root (often ``C:/``) or shortening the name of the Unreal Editor project.