Skip to content

Creating HALCON packages step by stepπŸ”—

Note

The description below often references the environment variable HALCONARCH, which is set during the installation. For more information about this variable, see the Installation reference.

Once the new operators have been described in DEF files and implemented (supply and action procedures) a couple of dynamic objects must be created (DLLs in Windows, shared libraries in Linux environments).

Important

Never change the name of a package or the corresponding names of the libraries/DLLs contained in a package.

These names are encoded within the libraries. If you change the names, this information will not match any longer, and the loader of the operating system will fail to open the dynamic libraries.

If you want to rename a package, create the libraries/DLLs again.

To activate a package, its complete path must be added to the environment variable HALCONEXTENSIONS, for example:

%HALCONEXAMPLES%\extension_package\halconuser

The package paths in HALCONEXTENSIONS are separated by semicolons (Windows) or colons (Linux); see also Installing extension packages.

Creating the operator librariesπŸ”—

The supply and action procedures must be encapsulated in a DLL (Windows) or shared library (Linux). The name of this shared object must be consistent with the package name (plus file extension).

For the use by HALCON XL, a second version of the library must be created, with the additional suffix xl to the name. For more information, see Additional information for specific platforms and the documentation of your programming environment.

Under Windows, the generated DLLs must be placed in the subdirectory bin\%HALCONARCH%, the libraries in the subdirectory lib\%HALCONARCH%. Under Linux, the generated shared libraries must be placed in the subdirectory lib/$HALCONARCH, binaries in the subdirectory bin/$HALCONARCH of the package. .NET assemblies must be placed in the subdirectory bin\dotnet.

Independent of whether you want to use the package in HDevelop or in a programming language, you must create the main interface library package. This library is based on a single C file Hpackage.c, which you can generate via

hcomp -H -ppackage <DEF file(s)>

Creating the interfacesπŸ”—

To access new HALCON operators inside a package within C programs, you must create a C interface library packagec residing in the subdirectory lib\%HALCONARCH% of the package. This library is based on a single C file HCpackage.c, which is generated from the DEF files of your new operators via

hcomp -C -ppackage <DEF file(s)>

hcomp simultaneously generates the file HCpackage.h containing the C prototypes of your new operators. Include this file in your C programs using these operators.

To access new HALCON operators inside a package within C++ programs, create a C++ interface library packagecpp residing in the subdirectory lib\%HALCONARCH% of the package. This library is based on the file HCPPpackage.cpp generated from the DEF files of your self developed operators via

hcomp -P -ppackage <DEF file(s)>

hcomp simultaneously generates the file HCPPpackage.h containing the C++ prototypes of your new operators. Include this file in your C++ programs using these operators.

To access new HALCON operators inside a package within .NET programs, create the interface assembly packagedotnet residing in the subdirectory lib\dotnet of the package. This assembly is based on the C# source file HDOTNETpackage.cs, which is generated from the DEF files of your new operators via

hcomp -N -ppackage <DEF file(s)>

Creating new applicationsπŸ”—

To create new application programs (written in C, C++, or .NET languages) based on your own HALCON operators, link the corresponding language interface libraries packagec or packagecpp to your objects, or reference the corresponding .NET assembly packagedotnet.

For C or C++ applications, you furthermore need the HALCON library itself and the HALCON/C or HALCON/C++ library, as for any HALCON application. For .NET applications, you need the HALCON/.NET assembly.

Additional information for specific platformsπŸ”—

The main differences between specific platforms concern the name handling and the generation of shared libraries or DLLs.

To activate a package, its complete path must be included in the environment variable HALCONEXTENSIONS, for example:
%HALCONEXAMPLES%\extension_package\halconuser

In the Windows version, the package paths in HALCONEXTENSIONS are separated by semicolons.

Important

DLLs must be stored in the subdirectory bin\%HALCONARCH% of the package, the corresponding libraries in the subdirectory lib\%HALCONARCH%.

  • Creating object files for the HALCON XL version:
    By default, using CMakeLists.txt, the package will be built with the normal version of HALCON. If you want to build with HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step. For this, use the following syntax:

    cmake -DHALCON_XL=1 %HALCONEXAMPLES%\extension_package\halconuser
    
  • Creating the operator DLL package.dll and the library package.lib:
    To create the operator DLL package.dll containing new HALCON operators and the corresponding library package.lib, link the object files containing the corresponding supply and action procedures and the HALCON library halcon.lib.

    To create the libraries packagexl.dll and packagexl.lib for HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step. Link the corresponding object files to the HALCON XL library halconxl.lib instead of halcon.lib.

  • Creating the C interface DLL packagec.dll and the library packagec.lib:
    To create the libraries packagec.dll and packagec.lib, which provide the C interface to new HALCON operators, link the object file HCpackage.obj, the new operator library package.lib, the HALCON C library halconc.lib, and the HALCON library halcon.lib.

    To create the libraries packagecxl.dll and packagecxl.lib for HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step. Link the corresponding object files to the HALCON XL version of the libraries, i.e., packagexl.lib, halconcxl.lib, and halconxl.lib.

  • Creating the C++ interface DLL packagecpp.dll and the library packagecpp.lib:
    To create the DLL packagecpp.dll providing the C++ interface to new HALCON operators and the corresponding library packagecpp.lib, link the object file HCPPpackage.obj, the new operator library package.lib, the HALCON C++ library halconcpp.lib and the HALCON library halcon.lib.

    To create the libraries packagecppxl.dll and packagecppxl.lib for HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step. Link the corresponding object files to the HALCON XL version of the libraries, i.e., packagexl.lib, halconcppxl.lib, and halconxl.lib.

  • Creating the .NET interface assembly packagedotnet.dll:
    The assembly packagedotnet.dll providing the .NET interface to new HALCON operators is created directly from the source file HDOTNETpackage.cs, together with the XML file that documents the content of the assembly.

    To create the assembly packagedotnetxl.dll for HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step.

  • Creating new applications:
    To create new application programs written in C or C++, link packagec.lib or packagecpp.lib to your objects. Furthermore, you will need halconc.lib or halconcpp.lib (as for any HALCON application). For .NET applications, you reference the libraries packagex.lib and halconx.lib or the assemblies packagedotnet.dll and halcondotnet.dll, respectively.

    To create a HALCON XL version of your application, just use the HALCON XL version of the libraries (e.g., packagecxl.lib and halconcxl.lib in case of a C application).

    To link the package DLL to your application program, add the complete DLL file path of the new package to the environment variable PATH, for example:
    %HALCONEXAMPLES%\extension_package\halconuser\bin\%HALCONARCH%

    This is also true for .NET applications.

    Important

    Do not copy a package DLL into the Windows system directories, as it would be loaded twice in this case!

If you encounter program crashes, check the stack size allocated by your application. A stack size of 6 to 8 MB is recommended.

The directory %HALCONEXAMPLES%\extension_package\halconuser contains the example CMake file CMakeLists.txt, which can be used to create the example package halconuser and the example applications based on the package halconuser. If required, download CMake (version 3.7.1 or later) from the CMake website and install it. To build the example package β€œhalconuser” using CMake, do the following:

mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=%HALCONEXAMPLES%\extension_package \
      %HALCONEXAMPLES%\extension_package\halconuser
cmake --build . --target install

By default, the normal version of HALCON is created. If you want to build using HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step.

To activate a package, its complete path must be included in the environment variable HALCONEXTENSIONS, for example:
$HALCONEXAMPLES/extension_package/halconuser

In the Linux version, the package paths in HALCONEXTENSIONS are separated by colons. See also Installing extension packages.

  • Compiling the source code:
    To generate shared libraries, you must produce position-independent code. For the gcc or g++ compiler, this is done using the option -fPIC. For gcc, we also recommend the options
    -march=pentium -mcpu=pentiumpro -ansi -fno-strict-prototype.

  • Creating object files for the HALCON XL version:
    By default, using CMakeLists.txt, the package will be built with the normal version of HALCON. If you want to build with HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step. For this, use the following syntax:

    cmake -DHALCON_XL=1 %HALCONEXAMPLES%\extension_package\halconuser
    
  • Creating the operator library libpackage.so:
    To create the operator library libpackage.so containing new HALCON operators, the object files containing the corresponding supply and action procedures must be linked. The linkage of shared libraries is done with ld -shared. Specify the desired name libpackage.so and location of the library with the ld option -o.

    To create the library libpackagexl.so for HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step. The corresponding object files must be linked.

  • Creating the C interface library libpackagec.so:
    To create the C interface library libpackagec.so providing the interface to new HALCON operators, link the object file HCpackage.o and the new operator library libpackage.so.

    To create the library libpackagecxl.so for HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step. Link the corresponding object file to the HALCON XL version of the operator library, i.e., libpackagexl.so.

  • Creating the C++ interface library libpackagecpp.so:
    To create the C++ interface library libpackagecpp.so providing the interface to new HALCON operators, link the object files HCPPpackage.o and HCPPpackageGlobal.o and the new operator lib libpackage.so.

    To create the library libpackagecppxl.so for HALCON XL, set the option HALCON_XL to ON or 1 in CMake during the configuration step. Link the corresponding object files to the HALCON XL version of the operator library, i.e., libpackagexl.so.

  • Creating the .NET interface assembly packagedotnet.dll:
    You can use the Mono compiler to create the assembly packagedotnet.dll providing the .NET interface to new HALCON operators. This assembly is based on the C# source file HDOTNETpackage.cs; see Creating the .NET interface.

    Note

    You need a successfully installed and configured version of Mono to create the assembly.

    Run the following commands in a shell:

    mcs HDOTNETpackage.cs /target:library /out:Hpackage.dll /doc:Hpackage.xml \
       /warn:1 -r:halcondotnet.dll
    

    To create an executable, reference the newly created assembly Hpackage.dll and the HALCON .NET assembly as well.

  • Creating new applications:
    To create new application programs written in C or C++, link libpackage.so and libpackagec.so or libpackagecpp.so to your objects (besides libhalcon.so and libhalconc.so or libhalconcpp.so as for any HALCON application). For .NET applications, reference the assemblies packagedotnet.dll and halcondotnet.dll.

    Furthermore, add the package library subdirectory lib/$HALCONARCH to the environment variable LD_LIBRARY_PATH.

    To create a HALCON XL version of your application, just use the HALCON XL version of the libraries (e.g., libpackagexl.so, libpackagecxl.so, libhalconxl.so, and libhalconcxl.so in case of a C application).