Compiling and linking

This section explains how to compile the examples supplied with the libraries and covers the following topics:

Views build system

Views uses the CMake cross-platform build generator tool as the primary build system. CMake generates the files needed by your build tool (GNU make, Visual Studio, and so forth) for building your applications with Views. CMake version 3.14 or above is required.

Compiling and linking with CMake

This section describes how Views could be integrated into a CMake-based project. You can use find_package() for views, ifc, charts, graph_layout, dataccess, maps, iljs, and studio components.

Using find_package(views REQUIRED) sets the variables shown in the following table:

Table 1   CMake variables

VIEWS_CORE_LIBRARIES

List of core libraries:

views;winviews for windows

views;xviews for unix (for Motif you must set mviews manually and use static build)

VIEWS_MAIN_LIBRARIES

Optional ilvmain lib for windows (declares WinMain())

VIEWS_LF_LIBRARIES

List of look-and-feel libraries installed with Views

VIEWS_COMPILE_OPTIONS

Compilation flags

VIEWS_LINK_OPTIONS

Link flags

Views Components

The Views libraries are grouped into components. The find_package(views REQUIRED) command sets a view_<component>_FOUND CMake variable to TRUE for each installed component. The possible values are: appframe, foundation, gadgets, gantt, grapher, manager, prototype. Note that some components might not be installed depending on which features of Views were selected during the installation.

CMake command line options

  • G — specifies the generator.

  • DCMAKE_GENERATOR_PLATFORM — Specifies system bitness. Possible values are x64, x86 (Unix only), or Win32 (Windows only).

  • DCMAKE_PREFIX_PATH — Defines lookup path for CMake packages. Point this to the CMake folder in the Views install directory. Files that are shipped with Views use the correct directory and do not need to be modified. For custom CMake files, set the path to %ILVHOME%/cmake on Windows or $ILVHOME/cmake on Unix.

  • DCMAKE_MODULE_PATH — Defines lookup path for CMake Find-modules. Point this to the CMake folder in the Views install directory. Files that are shipped with Views use the correct directory and do not need to be modified. For custom CMake files, set the path to %ILVHOME%/cmake on Windows or $ILVHOME/cmake on Unix.

  • DVISU_SYSTEM_NAME — Configures the Views system. Set it according to which Views binaries you wish to use. Possible values are x64_.net2019_16.0 for Windows or x64_rhel7.2_5.3 for Unix. A list of the installed versions can be found in the <Views install path>/lib directory. All supported OS and compiler combinations are also listed in the Views Supported Platform Guide.

  • DVISU_LINK_MODE — Configures the Views library link mode. Set it according to which Views binaries format you wish to use. Possible values are dll_mda, stat_mda, or stat_mta for Windows; and shared or static_pic for Unix. To use separately distributed debug Views libraries, add a "d" suffix to link mode: dll_mdad, stat_mdad, stat_mtad, sharedd, static_picd.

Views compilation flag

Refer to the following table for the Views compilation flags:

Table 2   Views compilation flags

IL_DLL

Includes code specifically for shared builds. Should be defined in case of using DLL Views libraries on Windows (dll_mda).

Example CMake

cmake_minimum_required(VERSION 3.14)

project(views_app VERSION 7.0 LANGUAGES CXX)

 

find_package(iljs REQUIRED)

find_package(ifc REQUIRED)

find_package(views REQUIRED)

find_package(Threads REQUIRED)

 

add_executable(${PROJECT_NAME}

   main.cpp

)

target_link_libraries(${PROJECT_NAME} PRIVATE

   ${VIEWS_CORE_LIBRARIES}

   ${VIEWS_MAIN_LIBRARIES}

   ${VIEWS_LF_LIBRARIES}

   ilvgadgt

)

target_compile_options(${PROJECT_NAME} PRIVATE ${VIEWS_COMPILE_OPTIONS})

target_link_options(${PROJECT_NAME} PRIVATE ${VIEWS_LINK_OPTIONS})

Let's assume your source directory contains main.cpp and CMakeLists.txt. From your build directory run CMake with a relative path to your project CMakeLists.txt file and an absolute path to <Views install path>/cmake.

On Windows:

cmake ../ -G "Visual Studio 16 2019" -DCMAKE_GENERATOR_PLATFORM=x64

-DCMAKE_PREFIX_PATH="<Views install path> /cmake"

-DVISU_SYSTEM_NAME="x64_.net2019_16.0" -DVISU_LINK_MODE=dll_mda

On Unix:

cmake ../ -G "Unix Makefiles" -DCMAKE_PREFIX_PATH="<Views install path>/cmake"

-DVISU_SYSTEM_NAME="x64_rhel7.2_5.3" -

DVISU_LINK_MODE=shared -DCMAKE_BUILD_TYPE=Release

make

If CMake reports errors trying to find the Views packages, double check your paths and use -DCMAKE_FIND_DEBUG_MODE=ON to gather more information on why CMake is not able to find the Views dependent packages.

Compiling and linking with Microsoft Visual C++

This section discusses the requirements for compiling your source files with Microsoft Visual C++.

Most of the binaries rely on the data files provided in the Views library, and you need to copy these files as well as the .EXE file when installing a program on another platform. You may also place these files in the resources bound to the executable.

The packing alignment for structure and union members is 8 bytes.

The libraries are standard C++ libraries and are in the following formats:

  • dll_mda: dynamic multi-threaded Views release libraries with dynamic runtime libraries

  • dll_mdad: dynamic multi-threaded Views debug libraries with dynamic runtime libraries

  • stat_mda: static multi-threaded Views release libraries with dynamic runtime libraries

  • stat_mdad: static multi-threaded Views debug libraries with dynamic runtime libraries

  • stat_mta: static multi-threaded Views release libraries with static runtime libraries

  • stat_mtad: static multi-threaded Views debug libraries with static runtime libraries

The following table lists the compilation flags to use:

Table 3   Compilation flags for Microsoft Visual C++

dll_mda

/DIL_DLL /MD /EHsc /GR /D_CRT_SECURE_NO_DEPRECATE

dll_mdad

/DIL_DLL /MDd /EHsc /GR /D_CRT_SECURE_NO_DEPRECATE

stat_mda

/MD /EHsc /GR /D_CRT_SECURE_NO_DEPRECATE

stat_mdad

/MDd /EHsc /GR /D_CRT_SECURE_NO_DEPRECATE

stat_mta

/MT /EHsc /GR /D_CRT_SECURE_NO_DEPRECATE

stat_mtad

/MTd /EHsc /GR /D_CRT_SECURE_NO_DEPRECATE

If you are using release Views libraries when compiling files in debug mode, you must use the non-debug version of the runtime libraries and undefine the macro DEBUG. This is because Views uses non-debug runtime libraries for release libraries. However, if you are using the separately distributed debug Views libraries, you must use the debug versions of the runtime libraries.

Compiling with GCC

Views libraries are standard C++ libraries and are provided in the following formats:

  • shared: dynamic Views release libraries

  • sharedd: dynamic Views debug libraries

  • static_pic: static Views release libraries

  • static_picd: static Views debug libraries

The following table lists the compilation flags to use:

Table 4   Compilation flags for GCC

shared

sharedd

static_pic

static_picd

Compilation options for GCC

When creating a CMake based project, it’s possible to specify extra compiler options for a target through the target_compiler_options CMake function. Some possible values for GCC are -Wall and -Wextra.

target_compile_options(${PROJECT_NAME} PRIVATE ${VIEWS_COMPILE_OPTIONS}-Wall -Wextra)

Typically, the options are applied only to client code and not to Views targets’ headers. In order to apply compiler options to external headers, add the following line to the project’s CMake file.

set_target_properties(${PROJECT_NAME} PROPERTIES NO_SYSTEM_FROM_IMPORTED ON)

Compiling samples

The Views installation comes with a set of sample programs that demonstrate the use of its libraries. These programs are in the `samples` directory, inside the main installation directory.

The user can build the samples using CMake. CMake defines the project structure and dependencies in a single file, and then generates a buildable project that is specific to the available platform and compiler.

Prerequisites

To build the samples, it is necessary to have CMake installed and to set the ILVHOME environment variable to the Views installation path. This can be done at system level, or simply in the terminal session used to build the samples.

Some samples require DBLink to be installed and discoverable. To do that, simply set also the ILDHOME environment variable to the DBLink installation path. If this is not done, those samples will be simply skipped.

Compiling

There are two ways of building the samples.

  • You can compile all samples at the same time and create a single buildable project.

  • Alternatively, you can compile each sample as a standalone project.

When compiling as a standalone project, copy the samples folder to an alternative location. Regardless of chosen approach, the steps to compile are the same.

  1. The first step consists in configuring the project. To do that, from the samples project folder run:

    cmake -B out

    If the command runs successfully, it creates a project in a new `out` folder. If desired, replace `out` with a different folder name.

  2. The next step consists in building the project. On Windows, running:

    cmake --open out

    opens the project in Visual Studio. Alternatively, the `out` folder contains a Visual Studio solution that can be opened with a double-click. The project can be then built using the IDE.

    On Linux, change into the `out` directory, and then run `make`.

    make

  3. There is a third alternative that works regardless of the host platform. From the same folder where the project was configured, run:

    cmake --build out

    This invokes the correct compiler and run the build in the terminal.

By default, the project is configured and built in debug mode and with dynamic linking (`dll_mda` on Windows and `shared` libraries on Linux).

To learn how to customize these and other aspects of the configuration, read the following Advanced Build section.

Advanced Build

Customizing the Build

The following parameters can be used to customize how the project is built. To use them, simply append them to the cmake -B out command described above.

  • CMAKE_BUILD_TYPE

    Controls whether the project is built in Debug or Release mode.

    For example: use -DCMAKE_BUILD_TYPE=Release to configure in project in Release mode.

  • VISU_LINK_MODE

    Controls whether the project uses Views libraries with static or dynamic linking.

    For example: add -DVISU_LINK_MODE=static_pic to configure static linking on Linux. See the previous sections for a list of accepted values.

  • VISU_SYSTEM_NAME

    Sets the project to use the libraries that are compiled for a specific platform. Views is typically installed with libraries for a single compiler (e.g., located under `lib/x64_.net2022_17.0`) and CMake will correctly link the project to those libraries. However, if multiple platforms were installed, the correct one can be selected by using VISU_SYSTEM_NAME.

    For example, add -DVISU_SYSTEM_NAME=x64_.net2019_16.0 to configure the project to use the libraries compiled for Visual Studio 2019.

Configuring Selected Samples

The following section is valid only when all samples are built as a single project from the `samples` directory.

The samples are grouped by topic into several directories (appframe, gadgets, dataccess, and so on). By default, CMake attempts to configure all samples directories. However, you can choose to configure only a selection of these directories by adding -DBUILD_<SAMPLE_DIR>_SAMPLES=ON for each selected directory.

Possible values for <SAMPLE_DIR> are: APPFRAME, CHARTS, FOUNDATION, GADGETS, GANTT, GRAPHER, LAYOUT, MANAGER, PROTOS, STUDIO, CSS, TUTORIALS, MAPS, DATACCESS.

A sample directory is configured only if it is enabled in the configuration (with -DBUILD_<SAMPLE_DIR>_SAMPLES) and the needed components have been found by the find _package(views REQUIRED) command. see the Views Components section.

Compiling Views Studio examples

To compile the Views Studio samples supplied with Views, use CMake with the provided /studio/CMakeLists.txt file. Use the same CMake options as for compiling Views samples.

Compiling Views tools

To compile the tools supplied with Views, use CMake with the provided /tools/CMakeLists.txt file. Use the same CMake options as for compiling Views samples.

Running samples

To run the samples, make sure to set your ILVHOME environment variable and any paths to the shared libraries your product is built to use.

For example, on Linux using a BASH style shell:

export ILVHOME=<Views install path>

export LD_LIBRARY_PATH=$ILVHOME/lib/x64_rhel8.0_8.2/shared:$ILVHOME

/studio/x64_rhel8.0_8.2/shared:$ILDHOME/lib/x64_rhel8.0_8.2/shared.

cd <Views samples>/out

./IlvButton_css_sample

For example, on Windows:

set ILVHOME="C:\Perforce\Views\7.0"

set PATH="%ILVHOME%\lib\x64_.net2019_16.0\dll_mda;%ILVHOME%
\studio\x64_.net2019_16.0\dll_mda;%ILDHOME%\lib\x64_.net2019_16.0\dll_mda;%PATH%"

cd <Views samples>\out

IlvButton_css_sample.exe

Linking to Views statically

Due to licensing reasons, it is not possible to statically link to Modest library. Modest must be linked dynamically. When using CMake and find_package(views) as explained in previous paragraphs, the dynamic linking to Modest library is already handled. It is only necessary to provide the Modest shared library when running the resulting application.