:orphan:

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

This document shows how to build :doc:`/sample_codes` provided within HOOPS Exchange installation package.

.. _samples_build:

.. tabs::

   .. group-tab:: CMake (All platforms)

      Since HOOPS Exchange 2025.4.0, we provide CMake support for our sample code.

      You need CMake version **3.20.2 or higher**.

      The example code projects follow a typical CMake workflow.  
      If you are familiar with CMake, no special steps are required.  
      If you are new to CMake, we recommend the `official tutorial from Kitware <https://cmake.org/cmake/help/latest/guide/tutorial/index.html>`__.

      To learn more or to download CMake, visit the `official website <https://cmake.org>`__.

      .. rubric:: Check if you have CMake

      You can check if CMake is installed by running the following command in your terminal or command prompt:

      .. code-block:: console

         cmake --version

      This will show the version of CMake on your system.
      If you do not have it, or if the version is lower than 3.20.2, you should install a newer version.

      You can download the installer from the `CMake downloads page <https://cmake.org/download/>`_.
      There are versions for Windows, macOS, and Linux.

      .. rubric:: Building sample code with the CMake UI

      CMake has a graphical interface that can help you set up your project step by step.
      This is available on Windows, macOS, and Linux.

      First, open the CMake application.

      * In the field **Where is the source code**, choose the folder that contains the sample code.
      * In the field **Where to build the binaries**, choose a different empty folder.
        This is where the build files will be created.

      Click the **Configure** button.
      CMake will ask you which compiler or tool you want to use (see :doc:`/start/supported-platforms`).
      After configuration, you will see some options you can change if needed.

      Click **Generate** to create the project files.
      
      Now you can open the generated project in your IDE and build it there.

      .. rubric:: Building sample code from the command line (POSIX)

      If you prefer to use the terminal, you can also run CMake from the command line.

      First, create a new folder for the build:

      .. code-block:: console

         $ mkdir build
         $ cd build

      Then run CMake with the path to the sample code:

      .. code-block:: console

         $ cmake ../path/to/samples -DCMAKE_BUILD_TYPE=Release

      If you want to choose a specific compiler or generator, you can add the ``-G`` option:

      .. code-block:: console

         $ cmake ../path/to/samples -G "Visual Studio 17 2022"

      Once CMake finishes, you can build the code with this command:

      .. code-block:: console

         $ cmake --build . --config Release

      CMake will automatically run the correct build tool, such as `make`, `ninja`, or `msbuild`, depending on what you selected.

      After building, you will find the compiled sample programs in the folder named ``sample_bin/`` at the root of your build directory.

   .. group-tab:: Windows
   
      #. **Build the solution**
      
         If you are on a Windows platform:

         * In the ``../samples/`` folder of your installed package, open the ``HOOPSExchangeSamples.sln`` file using Visual Studio.
         * Select the Debug, x64 mode.
         * Go to the tab *Build* and build the entire solution.

         Out of the box you should obtain: *Build: 18 succeeded, 2 failed, 0 up-to-date, 0 skipped.*
         
         The 2 failing samples are the ``.Net Wrapper`` (our HOOPS Exchange C# sample) and ``TranslateToPkParts`` (our *Bridge* to the `Siemens Parasolid API <https://www.techsoft3d.com/products/parasolid/>`__ ).

         This is the expected behavior as these two samples required further more configuration to run. (Download Microsoft .NET for Visual Studio and visit the `TranslateToPkParts <https://docs.techsoft3d.com/exchange/latest/guide/parasolid.html>`__ page for more details).

         .. image:: /_assets/images/vs-build-solution.png
            :width: 50%
            :align: center

      #. **Test a sample**

         In Visual Studio from the Solution Tree explorer:
                  * Locate the sample ``ImportExport``
                  * To run the sample, right click on it and select *Debug -> Start New Instance*.
                     * The sample will read a sample input file, **_Aquo Bottle.CATProduct**, and convert it to PRC format.
                     * The result file is located alongside the input file.
                  * Locate the newly created file **_Aquo Bottle.CATProduct.prc** in your output folder from the installation folder ``..\samples\data\catiaV5\CV5_Aquo_Bottle``
                  * Open the *HOOPS Demo Viewer* desktop application.
                  * Drag & drop your resulting **_Aquo Bottle.CATProduct.prc** file to quickly visualize the assembly:
                  
         .. image:: /_assets/images/AquaBottle.png
            :width: 50%
            :align: center

         For more details on using the *HOOPS Demo Viewer*, consult the `HDV Documentation Page <https://docs.techsoft3d.com/hdv/latest/>`__.

   .. group-tab:: Linux

      #. **Build the solution**
      
         If you are on a Linux platform:
                  * Locate the folder ``..\samples\`` from the installation folder.
                  * Right click on the folder and select *Open in Terminal*.
                  * In Terminal Type ``make`` to build all the samples.

         Out of the box all samples are built but the sample ``TranslateToPkParts``, our *Bridge* to the `Siemens Parasolid API <https://www.techsoft3d.com/products/parasolid/>`__ requires further more configuration to run, please visit the `TranslateToPkParts <https://docs.techsoft3d.com/exchange/latest/guide/parasolid.html>`__ page for more details.

         .. image:: /_assets/images/make_all_sample.png
            :width: 50%
            :align: center

      #. **Test a sample**

         The `HOOPS Demo Viewer application <https://docs.techsoft3d.com/hdv/latest/>`__ being a Windows only application, for Linux we will use the samples ``ImportExport`` AND ``Viewer`` instead.
         
                  * Locate the sample ``ImportExport`` from the installation folder ``..\samples\hello_world\ImportExport``
                  * Right click on the folder and select *Open in Terminal*.
                  * Locate the file **_Aquo Bottle.CATProduct** from the installation folder ``..\samples\data\catiaV5\``
                  * Make sure the sample is already built otherwise build it again: Command Line: ``make``
                  
         .. image:: /_assets/images/Import_export_make.png
            :width: 50%
            :align: center
            
         * *Run* the sample ``ImportExport`` to convert a CATIA V5 assembly called **_Aquo Bottle.CATProduct** to PRC format. 
         * Command Line : ``./ImportExport ..\samples\data\catiaV5\_Aquo Bottle.CATProduct ..\samples\data\catiaV5\_Aquo Bottle.CATProduct.prc``
         
         .. image:: /_assets/images/Import_export_output.png
            :width: 50%
            :align: center

         * Locate the resulting file **_Aquo Bottle.CATProduct.prc** from the installation folder ``..\samples\data\catiaV5\``
         * *Run* the sample ``Viewer`` to  load the PRC file in the OpenGL sample Viewer. Command Line ``./Viewer ..\samples\data\catiaV5\_Aquo Bottle.CATProduct.prc``
         * **_Aquo Bottle.CATProduct.prc** file will be displayed in an OpenGL Windows:
            
         .. image:: /_assets/images/viewer_sample.png
            :width: 50%
            :align: center
            

   .. group-tab:: macOS

      #. **Build the solution**
      
         If you are on a macOS platform:
                  * Locate the folder ``..\samples\`` from the installation folder.
                  * Open the *Terminal* and set the current directory to ``..\Samples``
                  * In Terminal Type ``make``

         Out of the box all samples are built but the sample ``TranslateToPkParts``, our *Bridge* to the `Siemens Parasolid API <https://www.techsoft3d.com/products/parasolid/>`__ requires further more configuration to run, please visit the `TranslateToPkParts <https://docs.techsoft3d.com/exchange/latest/guide/parasolid.html>`__ page for more details.
         
         .. image:: /_assets/images/build-mac-samples.png
            :width: 50%
            :align: center
            

      #. **Test a sample**

         The `HOOPS Demo Viewer application <https://docs.techsoft3d.com/hdv/latest/>`__ being a Windows only application, for macOS we will use the samples ``ImportExport`` AND ``Viewer`` instead.
         
                  * Locate the sample ``ImportExport`` from the installation folder ``..\samples\hello_world\ImportExport``
                  * Open the *Terminal* and set the working directory to ``..\samples\hello_world\ImportExport``
                  * Make sure the sample is already built otherwise build it again: Command Line: ``make``
                  
         .. image:: /_assets/images/make-importexport-mac.png
            :width: 50%
            :align: center
            
         * On macOS go to *System Settings* and open the *Privacy and Security* tab.
         * Check that the ``libA3DLIBS.xx.x.xx.dylib`` file is not blocked, is this is the case click *Allow Anyway*.
         
         .. image:: /_assets/images/privacy-security-mac.png
            :width: 50%
            :align: center
            
         * Locate the file **_Aquo Bottle.CATProduct** from the installation folder ``..\samples\data\catiaV5\``
         * *Run* the sample ``ImportExport`` to convert a CATIA V5 assembly called **_Aquo Bottle.CATProduct** to PRC format.
         * Command Line: ``./ImportExport ../samples/data/catiaV5/_Aquo Bottle.CATProduct ../samples/data/catiaV5/_Aquo Bottle.CATProduct.prc``
         
         .. image:: /_assets/images/import-export-mac.png
            :width: 50%
            :align: center
            

         * Locate the resulting file **_Aquo Bottle.CATProduct.prc** from the installation folder ``..\samples\data\catiaV5\``
         * *Run* the sample ``Viewer`` to  load the PRC file in the OpenGL sample Viewer. Command Line ``./Viewer ..\samples\data\catiaV5\_Aquo Bottle.CATProduct.prc``
         * **_Aquo Bottle.CATProduct.prc** file will be displayed in an OpenGL Windows:
         
         .. image:: /_assets/images/sample-viewer-mac.png
            :width: 50%
            :align: center
            
            
   .. group-tab:: iOS

         HOOPS Exchange is compatible with iOS, unlike the Windows, Linux and macOS platforms HOOPS Exchange for iOS support is limited to:
         
         * CAD Import formats: ``SolidWorks, IFC, IGES, JT, PARASOLID, PDF, PRC, STEP, STEPXML, U3D``
         * CAD Export formats: ``IGES, PARASOLID, STEP``
         
         The package contains the following folders: *bin, includes, samples, documentation*, the samples folder only contains two samples:
         
         * ``PRC2XML``: Sample describing how to load a CAD file and to dump the model tree structure, metadata, attributes and more.
         * ``IOSWriter``: Sample describing how to load a CAD file and to convert it to another format.
                  
      #. **Build the solution**

         * Launch Xcode and select *Open Existing Project*.
         * In the ``../samples/ios/PRC2XML`` folder of your installed package, open ``PRC2XML.xcodeproj``
         
         .. image:: /_assets/images/prc2xml-ios.png
            :width: 50%
            :align: center

         * From the *Project navigator* bar select the file ``ts-0000.prc``
         * Right Click ``Add files to "PRCXML"...``
         
         .. image:: /_assets/images/add-files-prc2xml-ios.png
            :width: 50%
            :align: center

         * Build the sample.
         * Go to the tab ``Product`` > ``Build For`` > ``Running``
         
         .. image:: /_assets/images/build-prc2xml-ios.png
            :width: 50%
            :align: center
            
            
      #. **Test a sample**
                     
         * Run the sample ``PRC2XML``
         * Go to the tab ``Product`` > ``Run``
          
         .. image:: /_assets/images/run-prc2xml-ios.png
            :width: 50%
            :align: center
            

         * The iOS simulator will be launched:
         * Click on the ``ts-0000.prc`` 
         * The ``ts-0000.prc.xml`` file will be generated containing the dump of the PRC file structure in your output folder:
         
         ``/Users/me/Library/Developer/CoreSimulator/Devices/XXXX/data/Containers/Data/Application/XXXX/Documents``
         
         .. image:: /_assets/images/simulator-ios.png
            :width: 50%
            :align: center
            

         * The file ``ts-0000.prc`` is the result of a CAD file being imported and converted to PRC format by HOOPS Exchange
         * The resulting ``ts-0000.prc.xml`` file is the dump of the tree structure of the PRC file.
         * Open the XML file to navigate the structure and the dump of the CAD file.
         
         .. image:: /_assets/images/xml-ios.png
            :width: 50%
            :align: center
            

            

   .. group-tab:: Android

      Coming soon... 
