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

This page shows how to build the :doc:`sample code </sample_codes>` shipped with HOOPS Exchange.

.. sidebar::

   .. contents::
      :local:
      :depth: 2

.. _desktop_platforms:

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

Before you start, you need:

- **CMake 3.21 or later**, from `cmake.org <https://cmake.org/download/>`__ or your package manager.
- **A C++ compiler**. See :doc:`/start/supported-platforms`.
- **A HOOPS Exchange license**. See :ref:`tuto_init_license`.

You don't need to write any CMake code or set environment variables.
The samples find HOOPS Exchange in the package on their own.

.. _samples_build_all:

Build All Samples
-----------------

Run these commands from the *samples/* folder of your HOOPS Exchange package:

.. code-block:: console

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

Executables are placed in *build/bin/*.
On Windows, they go into a *Debug/* or *Release/* subfolder.

.. _samples_build_one:

Build a Single Sample
---------------------

Each sample is a build target named after its folder.
For instance, to build only *hello_world/ImportExport*:

.. code-block:: console

   cmake -B build
   cmake --build build --target ImportExport

You only need to run ``cmake -B build`` once.
After that, build any sample with ``cmake --build build --target <SampleName>``.
To build several samples at once, list them after ``--target``.

See :doc:`/sample_codes` for the list of samples.

.. _samples_run:

Run a Sample
------------

.. code-block:: console

   ./build/bin/ImportExport                  # Linux, macOS
   build\bin\Debug\ImportExport.exe          # Windows

The location of the HOOPS Exchange binaries and of the sample data is compiled into each sample, so you can run it from *build/bin/* without any further setup.

.. _samples_build_make:

Keep Using Make (Linux, macOS)
------------------------------

On Linux and macOS, ``cmake -B build`` generates regular Makefiles by default.
Run it once, and then build with ``make`` as usual:

.. code-block:: console

   cmake -B build                   # once
   make -C build -j8                # all samples
   make -C build ImportExport       # a single sample

.. note::

   The standalone Makefiles previously shipped in the samples folder were removed in HOOPS Exchange 2026.6.0.

.. _samples_build_msvc:

Build with Visual Studio (Windows)
----------------------------------

The Windows package includes a ready-made solution, so CMake is not needed:

1. Open *samples/HOOPSExchangeSamples.sln*.
2. Select the *Debug* or *Release* configuration.
3. To build every sample, select *Build -> Build Solution* (**Ctrl+Shift+B**).
   To build a single sample, right-click it in *Solution Explorer* and select *Build*.
4. To run a sample, right-click it, select *Set as Startup Project*, then press **F5**.

.. 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_xcode:

Build with Xcode (macOS)
------------------------

Generate an Xcode project and open it:

.. code-block:: console

   cmake -B build -G Xcode
   open build/HOOPSExchangeSample.xcodeproj

Select a sample in the scheme dropdown, then select *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*.

.. _samples_build_ide:

Build from Another IDE
----------------------

Visual Studio (*File -> Open -> Folder*), Visual Studio Code with the CMake Tools extension, CLion, and Qt Creator open CMake projects directly.
Open the *samples/* folder and select a sample to build and run it from the IDE.

.. _samples_options:

Build Options
-------------

Add any of these options to the ``cmake -B build`` command, for instance ``cmake -B build -DHOOPS_BUILD_PUBLISH=OFF``:

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Option
     - Effect
   * - ``-DCMAKE_BUILD_TYPE=Release``
     - Builds in release mode on Linux and macOS.
       On Windows, and with Xcode, add ``--config Release`` to the ``cmake --build`` command instead.
   * - ``-DHOOPS_BUILD_PUBLISH=OFF``
     - Skips the publishing samples.
   * - ``-DHOOPS_EXCHANGE_DISABLE_SAMPLES_VIEWER=ON``
     - Skips the *Viewer* and *MeshViewer* samples.
       Use it on Linux if OpenGL or GLUT development packages are missing.
   * - ``-DPARASOLID_INSTALL_DIR=<path>``
     - Builds *TranslateToPkParts*, which is skipped when Parasolid is not found.
   * - ``-DA3DLIBS_ROOT=<path>``
     - Points to your HOOPS Exchange package if you moved the *samples/* folder out of it.

.. _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.
