Getting Started

The chapter describes how to get started with the API.

After installing the API, follow the steps below:

  1. Open a shell/command prompt where compiler is reachable.

    Note:
    Under Windows open the Visual Studio command prompt: Start/Visual Studio 2022. This opens a directory where you have to select x64 Native Tools Command Prompt. In order for the environment for Visual Studio 64Bit to be set correctly, the 64Bit Visual Studio Prompt must be started via start menu.
    Note:

    If you are using newer Visual Studio version but have older compiler installed, you can open the Visual Studio prompt with the following command. Example for Visual Studio 2022 (V17) Enterprise Edition:

    "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x64 -vcvars_ver=14.4x

  2. Set the environment variable API_ROOT to the directory where API was installed (wincc_oa_path/api):

    Examples

    Windows cmd:

    set API_ROOT=C:\Siemens\Automation\WinCC_OA\3.20\api

    C-Shell:

    setenv API_ROOT /opt/WinCC_OA/3.20/api

    Bash, Bourne-Shell:

    export API_ROOT=/opt/WinCC_OA/3.20/api

  3. Check the correct environment:

    The right environment is required for executing the new* scripts.

    Windows:

    Enter the command %API_ROOT%\checkApiEnv into the shell.

    The following output is displayed:

    -------
found API_ROOT - good
found VC14.4x compiler - good
found cmake - good
done
-------

    Linux:

    Check whether the required GCC Version is installed:

    gcc -v
  4. Create a directory for the project and navigate to the directory you created.

  5. Create a project from template by use of a script.

    Following template scripts are located in the API_ROOT directory:

    Script name Description
    newWCCILManager create a Manager developer project.
    newWCCILDriver create a Driver developer project.
    newWCCILCtrlExt create a CTRL extension DLL (plug-in) developer project.
    newEWO create an EWO (External Widget Object) developer project as plug-in for panels.
    newWCCOAAccessControlPlugin create a developer project for an AccessControl plug-in dll as plug-in for all managers.
    newWCCILErrHdl create a developer project for n external error handler dll as plug-in for all managers.

    You can call the scripts by using the following command:

    Windows: 

    %API_ROOT%\new<scriptname>.cmd <projectname>

    Linux: 

    $API_ROOT/new<scriptname>.sh <projectname>

    All the scripts create a cmake project.

  6. Create build directory (e.g. build) in the root directory of your project.

  7. Use a generator of your choice to create the build directory:

    cmake .. -G <generator>

    You can display a list of generators via:

    cmake --help

    Example:

    In case of Visual Studio cmake generator, use the following cmake arguments to set the correct Visual Studio Version and compiler version:

    cmake -G "Visual Studio 16 2019" -A "x64" -T "v142" ..
    Note:

    We recommend to use one of following generators:

    • Visual Studio (on Windows)
    • Ninja
    • Unix Makefiles

  8. Start the build.

    Build step is dependent on chosen cmake generator.

    In case of Visual Studio you can open the generated solution file and build it by using:

    devenv <projectname>.sln

    In case of "make" generator simple execute:

    make

    Or you can also use a generator-independent command:

    cmake --build . --config RelWithDebInfo