######################
Building Code Examples
######################

This guide explains how to build the :doc:`sample code </sample_codes>` included in your HOOPS Exchange installation package.

.. sidebar::

   .. contents::
      :local:
      :depth: 3

Quick Start
===========

For desktop platforms (Windows, Linux, macOS with CMake):

.. code-block:: console

   cd /path/to/HOOPS_Exchange/samples
   cmake -B build
   cmake --build build/

Executables are placed in ``build/bin/``.
For platform-specific options, IDE integration, or mobile platforms, see the sections below.

.. _desktop_platforms:

Desktop Platforms
=================

Prerequisites
-------------

Starting from HOOPS Exchange 2026.3.0, **CMake is the recommended build system** for all desktop platforms.
CMake generates native project files for your preferred IDE or build tool.

You need:

- **CMake 3.21 or higher** - Download from `cmake.org <https://cmake.org/download/>`__
- **A C++ compiler** - See :doc:`/start/supported-platforms` for supported compilers

.. tip::

   New to CMake? Start with the `official CMake tutorial <https://cmake.org/cmake/help/latest/guide/tutorial/index.html>`__.

.. _samples_configure:

Configuring with CMake
----------------------

CMake generates project files for your chosen build system (Visual Studio, Xcode, Make, Ninja, etc.).

Using CMake GUI
^^^^^^^^^^^^^^^

1. Open the CMake application.

2. Set the paths:

   - **Where is the source code**: Select the *samples/* folder from your HOOPS Exchange installation.
   - **Where to build the binaries**: Select an empty folder (e.g., *samples/build/*).

   .. figure:: cmake_configure.png
      :align: center
      :width: 75%

      Example: HOOPS Exchange extracted to /Users/hoopsy/Downloads/HOOPS_Exchange_2026.2.0/

3. Click **Configure** and select a generator:

   - *Visual Studio 17 2022* for Windows
   - *Xcode* for macOS
   - *Unix Makefiles* for Linux/macOS command line

4. Click **Generate** to create the project files.

5. Click **Open Project** to launch your IDE, or navigate to the build folder manually.

Using the Command Line
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

   cd /path/to/HOOPS_Exchange/samples
   cmake -B build

To specify a generator explicitly:

.. code-block:: console

   cmake -B build -G "Visual Studio 17 2022"   # Windows
   cmake -B build -G "Xcode"                   # macOS
   cmake -B build -G "Unix Makefiles"          # Linux/macOS

Next Steps
^^^^^^^^^^

Your project is now configured. If you selected an IDE generator (Visual Studio, Xcode), you can click the **Open Project** button in CMake GUI to launch your IDE directly.

Now proceed to build using your preferred method:

* `Build with CMake (All Platforms)`_
* `Build with Visual Studio (Windows)`_
* `Build with Make (Linux/macOS)`_
* `Build with Xcode (macOS)`_

.. _samples_build:

Build the Samples
-----------------

.. _samples_build_cmake:

Build with CMake (All Platforms)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The simplest approach - CMake invokes the appropriate build tool automatically:

.. code-block:: console

   cmake --build build/

For a Release build:

.. code-block:: console

   cmake --build build/ --config Release

Compiled executables are placed in ``build/bin/``.

.. _samples_build_msvc:

Build with Visual Studio (Windows)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Using CMake-generated solution:**

1. Open ``build/HOOPSExchangeSample.sln`` in Visual Studio.

**Using pre-built solution (Windows package only):**

1. Open ``samples/HOOPSExchangeSamples.sln`` directly - no CMake required.

**Build and run:**

1. Select *Debug* or *Release* configuration from the toolbar.
2. Build the solution: *Build -> Build Solution* (**Ctrl+Shift+B**).
3. To run a sample, right-click it in *Solution Explorer*, select *Set as Startup Project*, then press **F5**.

Compiled executables are placed in the *bin/* folder.

.. note::

   Two samples require additional setup:

   - **.NET Wrapper**: Install Microsoft .NET for Visual Studio.
   - **TranslateToPkParts**: See the `Parasolid bridge documentation <https://docs.techsoft3d.com/exchange/latest/guide/parasolid.html>`__.

.. _samples_build_make:

Build with Make (Linux/macOS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Using CMake-generated Makefiles:**

.. code-block:: console

   cd build/
   make -j$(nproc)      # Linux (parallel build)
   make -j$(sysctl -n hw.ncpu)   # macOS (parallel build)

Compiled executables are placed in ``build/bin/``.

**Using legacy Makefiles (without CMake):**

The Linux and macOS packages include standalone Makefiles:

.. code-block:: console

   cd /path/to/HOOPS_Exchange/samples
   make              # Build all samples
   make DEBUG=1      # Debug build
   make clean        # Clean build artifacts

With legacy Makefiles, executables are placed alongside each sample's source files.

.. _samples_build_xcode:

Build with Xcode (macOS)
^^^^^^^^^^^^^^^^^^^^^^^^

1. Generate an Xcode project:

   .. code-block:: console

      cmake -B build -G Xcode

2. Open the project:

   .. code-block:: console

      open build/HOOPSExchangeSample.xcodeproj

3. Select a sample from the scheme dropdown (next to the Stop button).

4. Build: *Product -> Build* (**Cmd+B**).

5. Run: *Product -> Run* (**Cmd+R**).

.. figure:: build_xcode.png
   :align: center
   :width: 75%

.. note::

   On first run, macOS may block the HOOPS Exchange library.
   Go to *System Settings -> Privacy & Security* and click *Allow Anyway*.

.. _desktop_platforms_end:

.. _mobile_platforms:

Mobile Platforms
================

Mobile platforms have limited CAD format support and fewer samples compared to desktop.

.. _ios_samples:

iOS
---

**Supported formats:**

- **Import**: SolidWorks, IFC, IGES, JT, Parasolid, PDF, PRC, STEP, STEPXML, U3D
- **Export**: IGES, Parasolid, STEP

**Available samples:**

- **PRC2XML**: Loads a CAD file and dumps the model tree, metadata, and attributes to XML.
- **IOSWriter**: Loads a CAD file and converts it to another format.

**Package contents:** *bin/*, *includes/*, *samples/*, *documentation/*

Build the iOS Samples
^^^^^^^^^^^^^^^^^^^^^

1. Open the Xcode project at ``samples/ios/PRC2XML/PRC2XML.xcodeproj``.

   .. image:: /_assets/images/prc2xml-ios.png
      :width: 75%
      :align: center

2. In the *Project navigator*, select ``ts-0000.prc``, then right-click and choose *Add files to "PRC2XML"...*.

   .. image:: /_assets/images/add-files-prc2xml-ios.png
      :width: 75%
      :align: center

3. Build the sample: *Product -> Build For -> Running*.

   .. image:: /_assets/images/build-prc2xml-ios.png
      :width: 75%
      :align: center

Running on the iOS Simulator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Run the sample: *Product -> Run*.

   .. image:: /_assets/images/run-prc2xml-ios.png
      :width: 75%
      :align: center

2. The iOS Simulator launches. Tap ``ts-0000.prc`` to process the file.

   .. image:: /_assets/images/simulator-ios.png
      :width: 75%
      :align: center

3. The generated ``ts-0000.prc.xml`` file is saved to the app's Documents folder:

   ``~/Library/Developer/CoreSimulator/Devices/<DEVICE_ID>/data/Containers/Data/Application/<APP_ID>/Documents``

4. Open the XML file to explore the PRC structure, metadata, and attributes.

   .. image:: /_assets/images/xml-ios.png
      :width: 75%
      :align: center

.. note::

   The iOS samples are Swift applications that use C++ bridging headers to call HOOPS Exchange APIs.

.. _android_samples:

Android
-------

**Available samples:**

- **PRC2XML**: Loads a CAD file and dumps the model tree structure to XML.

Build the Android Sample
^^^^^^^^^^^^^^^^^^^^^^^^

1. Open Android Studio.

2. Go to *File -> Open* and select ``samples/android/PRC2XML/``.

3. If prompted about missing SDK components, click the messages to install them (NDK, SDK, etc.).

4. Wait for Gradle sync to complete (watch the progress bar at the bottom).

5. Build: *Build -> Rebuild Project*.

6. Run: *Run -> Run 'app'* (**Shift+F10**) and select your device or emulator.

.. warning::

   **Path length limitation (Windows):** If you see errors about paths exceeding 240 characters, move the project closer to the drive root (e.g., ``C:\dev\PRC2XML``).

.. note::

   The Android sample uses Java with JNI to call HOOPS Exchange C++ APIs.
   Native code is built via CMake through the Android NDK.
