==========
Deployment
==========

How to build
------------

APEX 1.4 requires PhysX 3.4 to build when build with PhysX.

To build the APEX projects in this distribution, the PhysX SDK path in the
nxpath.vsprops files must be modified.  The UpdatePhysXPaths.vbs script is
provided for this purpose.  It will modify the nxpath.vsprops files under
the compiler folders. See the readme.txt at the top level of the APEX
distribution for details.

We recommend at least Microsoft Visual Studio 2010 SP1 to build APEX.

.. _deployment-build-configs-label:

Build Configurations
--------------------

APEX ships in four configurations: release, profile, checked, and debug.

release
  The release configuration of APEX is built for minimal footprint and maximum
  speed. It omits most checks and instrumentation. Debug visualization and
  asset authoring are not available in the release configuration.

profile
  The profile configuration of APEX supports PVD profiling and memory
  tracking, asset authoring, and debug visualization. It also supports kernel
  profiling on Windows, which uses 128 MB of video memory for a profiling
  buffer.

checked
  The checked configuration of APEX supports PVD profiling and memory
  tracking, asset authoring, debug visualization, and runtime assertions. It does not support
  kernel profiling on Windows. Unlike PhysX, the APEX checked configuration
  does not contain extra code to detect bad user input, so it should not be
  significantly slower than other configurations.

debug
  The debug configuration of APEX is an unoptimized build that supports PVD
  profiling and memory tracking, asset authoring, debug visualization, and 
  runtime assertions.

Our recommendation when using PhysX 3.x is to develop with *checked*,
profile with *profile*, and ship with *release*.

**PhysX 3.x**: APEX and PhysX 3.x contain shared code, so it is
important that the configurations match. For example, if you link to the
checked PhysX build you must also link to the checked APEX build.

============= ============ ==================== 
PhysX version PhysX config Use this APEX config
============= ============ ==================== 
3.x           release      release 
3.x           profile      profile 
3.x           checked      checked 
3.x           debug        debug
============= ============ ==================== 

The legacy module
-----------------

APEX standard modules are only able to load the latest version of APEX
assets. The legacy module (APEX_Legacy) is used for loading older versions of APEX assets.
For example, the 1.2.0 version of APEX_Clothing can only load APEX 1.2.0
clothing assets, but APEX_Legacy can also load assets from APEX 1.1
or 1.0. 

If you upgrade your APEX version during development, you should update all
your APEX assets to the latest version before shipping your application.
When you serialize an APEX asset it is automatically stored as the latest
version, so upgrading is as simple as deserializing and serializing all APEX
assets.

The legacy module is typically used during application development, but
shouldn't need to be shipped with the application.

For more information on serializing assets for specific platforms, see 
:ref:`nxparam-serialization-label`.

What to ship
------------

Typically your application should ship with the release configuration of
APEX. An exception would be if you want to give end users the ability to
author APEX assets, for example if you include a game editor with your game.
In that case you would want to ship with the profile or checked
configuration instead, because the release configuration strips out all
authoring code.

You do not typically need to ship the legacy module at all.

You do not typically need to link every APEX library with your application.
Here are the libraries you need to include with your application for each
APEX feature. These examples list the Win32 DLLs, but substitute the equivalent
name for your platform. For example, APEX_Clothing_x86.dll could
be APEX_Clothing.a or APEX_Clothing.lib.

**Clothing**

- ApexFramework_x86.dll
- APEX_Clothing_x86.dll
- APEX_ClothingGPU_x86.dll (only needed for GPU support on Windows)
- PhysX3Gpu_x86.dll (only needed for GPU support on Windows)
- PhysXDevice.dll (only needed for GPU support on Windows)

**Destructibles**

- ApexFramework_x86.dll
- APEX_Destructible_x86.dll

**APEX Particles** (Windows only)

- ApexFramework_x86.dll
- APEX_Particles_x86.dll
- PhysX3Gpu_x86.dll
- PhysXDevice.dll

**Turbulence** (Windows only)

- ApexFramework_x86.dll
- APEX_Particles_x86.dll
- APEX_Turbulence_x86.dll
- PhysX3Gpu_x86.dll
- PhysXDevice.dll

**Force Fields** (PhysX 3.x only)

- ApexFramework_x86.dll
- APEX_Particles_x86.dll
- PhysX3Gpu_x86.dll
- PhysXDevice.dll

Application GUID (Windows only)
-------------------------------

If your application employs APEX modules that use CUDA and you have made
local modifications to your APEX DLLs, you should use a GUID so that patches
for new GPU architectures can be released for your application. You can
obtain a GUID for your application from NVIDIA. If you do not pass your own
GUID into APEX, when future patches are released you will get the default
patched version of APEX, which could be problematic if you've modified APEX.
Also, remember that you should also pass this same GUID to PhysX when you 
create the PhysX SDK and the CUDA Context Manager.

Give the application GUID to APEX through the
`nvidia::apex::ApexSDKDesc <../_static/build_framework/classphysx_1_1apex_1_1_nx_apex_s_d_k_desc.html>`_
when creating the APEX SDK.

Give the application GUID to the CUDA Context Manager through the
`physx::PxCudaContextManagerDesc <../_static/build_pxtask/classphysx_1_1_px_cuda_context_manager_desc.html>`_
when creating the CUDA Context Manager.
