This article illustrates the process of using CMake utility to setup and generate a Microsoft Visual Studio Solution (.sln) to build the example C++ 3D PDF applications from the PDF3D-SDK developer toolkit package. This goes through configuration, SLN generation, Compiling, Running and viewing the output 3D PDF. Using this combination of tools, new 3D PDF desktop applications for MS-Windows can be created with the ability to generate interactive 3D PDF document files. The process is broken down into 10 separate steps (for C# see How to Build PDF3D-SDK C# .NET Examples with Visual Studio).

How to Build with C++

1. First up, install the PDF3D-SDK package and activate the license. Contact [email protected] if you’d like to discuss trying this process. Once installed, the PDF3D-SDK folder structure is available. Navigate to the examples/ folder first. Here there are many small source-code examples provided for training, getting started, and to illustrate various features available in the SDK. The SDK can be installed anywhere; however, it should be open for full read-write permissions since the example will be compiled inside this folder structure.Next navigate into the ReportExampleIS/ folder. This one will be used, for no particular reason other than it is fairly generic and makes a good starting point.

2. Once inside the ReportExampleIS/ folder, create a new empty folder, for this example it will be named build/, which is a common convention for cmake projects. If it already exists, remove all content so it is empty again. This empty folder will be used in the next step.

3. Now back to the PDF3D-SDK and tool-chain, CMake (available from www.cmake.org) must be installed, and have Start-Menu links as shown here. CMake comes with both a command-line program and a user-interface (GUI) version. To guide first use, the GUI version with visible menus is recommended. Click on the CMake (cmake-gui) program icon.

4. Once CMake starts, there are two fields at the top where the SOURCE and the BINARY parts of the project are specified. For this example, specify the ReportExampleIS/ folder as the SOURCE, and specify the new empty build/ folder for where the BINARY files of the build should go. Just one more thing, it is preferable to tick the check-boxes for Grouped and Advanced, but of course this is optional and can be changed any time, it does not affect the actual process. Finally click Configure.

5. Once the Configure button is pushed the first time for this project, a dialog is presented to select the compiler configuration to use. This is very important. The compiler type must be selected for files actually available in the PDF3D-SDK, ask or check the release notes if unsure. The actual Microsoft Visual Studio compiler version must be available. And finally, the selection of 32-bit or 64-bit versions must all match up with what’s installed. In the following illustration, Microsoft Visual Studio 2017 (15.0) 64-bit is selected. Note if this is set incorrectly, the generation process will continue, but the solution build will fail in unexpected ways, where the cause of the error will not be obvious.

6. After the first configuration pass, CMake presents candidate settings from what it found. In most cases the Configure button can be pushed a second time to confirm those settings. The groups can be opened up and changes made if required, before configuring a second time. Look out for any error messages in the log box. When all is OK, the final message “Configuring done” is expected.

7. Next, push the Generate button. This starts the process of creating the actual Visual Studio .sln solution that will be used to build the application. After this phase is complete, the log message “Generating done” is expected.

8. Now CMake can be closed down, or left open and use the Open Project button, as it is not needed any longer in this session. Going back to the files, the build/ folder is no longer empty, various visual studio project files have been created. The one to use is called ReportExampleIS.sln, i.e. the project specific solution file for this PDF3D stand-alone example. This solution file can be started (or use the CMake open project menu button). It should find the correct compiler automatically. If not, then start Visual Studio independently and load this solution.

9. The visual studio project has all the settings, paths and resources specified to build this example application. The small example source-code file Main.cpp can be explored (and potentially modified for further experiments). The default solution is set to Debug and x64. The PDF3D-SDK comes with both debug and release libraries, either one can be selected for building. Don’t touch x64, as this depends on what SDK version is installed and how CMake generated things. The Build action is next, where the project is compiled, linked and a new program ReportExampleIS.exe is created. This is normally created in the PDF3D-SDK/bin/VS2017/ folder, based on the PDF3D_ROOT environment variable (created at PDF3D-SDK installation time).

10. Once the build is completed, locate and run this small command-line application program. Console log messages are generated to show progress through the example, finally generating an output PDF file in the same folder.

11. Once the program has run, generated the output PDF and stopped, the PDF file can be opened and viewed. In this example it has a 3D view with a color surface, mesh lines shown, a clipping plane, title, caption and color-bar legend. For this example the filename matches the example program, and is ReportExampleIS.pdf.

In summary, CMake is able to create solutions for just about any supported compiler type, which avoids issues of porting and migrating .sln files from one compiler to another, and it also supports Linux and Mac environments. Just about all the PDF3D-SDK examples can be built in a similar way using this combination of CMake and Visual Studio.

Please get in touch to let us know if this walk-through is helpful, or for any further questions.

A narrated Video demo of this process is available at:

https://vimeo.com/287323040

https://youtu.be/mCtJUT7yUJM

https://www.pdf3d.com/pdf3d-videos/?zoombox=34

For more information about PDF3D-SDK see https://www.pdf3d.com/products/pdf3d-sdk/