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:
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
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 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 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
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, usingCMakeLists.txt, the package will be built with the normal version of HALCON. If you want to build with HALCON XL, set the optionHALCON_XLtoONor1in CMake during the configuration step. For this, use the following syntax: -
Creating the operator DLL
package.dlland the librarypackage.lib:
To create the operator DLLpackage.dllcontaining new HALCON operators and the corresponding librarypackage.lib, link the object files containing the corresponding supply and action procedures and the HALCON libraryhalcon.lib.To create the libraries
packagexl.dllandpackagexl.libfor HALCON XL, set the optionHALCON_XLtoONor1in CMake during the configuration step. Link the corresponding object files to the HALCON XL libraryhalconxl.libinstead ofhalcon.lib. -
Creating the C interface DLL
packagec.dlland the librarypackagec.lib:
To create the librariespackagec.dllandpackagec.lib, which provide the C interface to new HALCON operators, link the object fileHCpackage.obj, the new operator librarypackage.lib, the HALCON C libraryhalconc.lib, and the HALCON libraryhalcon.lib.To create the libraries
packagecxl.dllandpackagecxl.libfor HALCON XL, set the optionHALCON_XLtoONor1in CMake during the configuration step. Link the corresponding object files to the HALCON XL version of the libraries, i.e.,packagexl.lib,halconcxl.lib, andhalconxl.lib. -
Creating the C++ interface DLL
packagecpp.dlland the librarypackagecpp.lib:
To create the DLLpackagecpp.dllproviding the C++ interface to new HALCON operators and the corresponding librarypackagecpp.lib, link the object fileHCPPpackage.obj, the new operator librarypackage.lib, the HALCON C++ libraryhalconcpp.liband the HALCON libraryhalcon.lib.To create the libraries
packagecppxl.dllandpackagecppxl.libfor HALCON XL, set the optionHALCON_XLtoONor1in CMake during the configuration step. Link the corresponding object files to the HALCON XL version of the libraries, i.e.,packagexl.lib,halconcppxl.lib, andhalconxl.lib. -
Creating the .NET interface assembly
packagedotnet.dll:
The assemblypackagedotnet.dllproviding the .NET interface to new HALCON operators is created directly from the source fileHDOTNETpackage.cs, together with the XML file that documents the content of the assembly.To create the assembly
packagedotnetxl.dllfor HALCON XL, set the optionHALCON_XLtoONor1in CMake during the configuration step. -
Creating new applications:
To create new application programs written in C or C++, linkpackagec.liborpackagecpp.libto your objects. Furthermore, you will needhalconc.liborhalconcpp.lib(as for any HALCON application). For .NET applications, you reference the librariespackagex.libandhalconx.libor the assembliespackagedotnet.dllandhalcondotnet.dll, respectively.To create a HALCON XL version of your application, just use the HALCON XL version of the libraries (e.g.,
packagecxl.libandhalconcxl.libin 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 thegccorg++compiler, this is done using the option-fPIC. Forgcc, we also recommend the options
-march=pentium -mcpu=pentiumpro -ansi -fno-strict-prototype. -
Creating object files for the HALCON XL version:
By default, usingCMakeLists.txt, the package will be built with the normal version of HALCON. If you want to build with HALCON XL, set the optionHALCON_XLtoONor1in CMake during the configuration step. For this, use the following syntax: -
Creating the operator library
libpackage.so:
To create the operator librarylibpackage.socontaining new HALCON operators, the object files containing the corresponding supply and action procedures must be linked. The linkage of shared libraries is done withld -shared. Specify the desired namelibpackage.soand location of the library with theldoption-o.To create the library
libpackagexl.sofor HALCON XL, set the optionHALCON_XLtoONor1in CMake during the configuration step. The corresponding object files must be linked. -
Creating the C interface library
libpackagec.so:
To create the C interface librarylibpackagec.soproviding the interface to new HALCON operators, link the object fileHCpackage.oand the new operator librarylibpackage.so.To create the library
libpackagecxl.sofor HALCON XL, set the optionHALCON_XLtoONor1in 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 librarylibpackagecpp.soproviding the interface to new HALCON operators, link the object filesHCPPpackage.oandHCPPpackageGlobal.oand the new operator liblibpackage.so.To create the library
libpackagecppxl.sofor HALCON XL, set the optionHALCON_XLtoONor1in 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 assemblypackagedotnet.dllproviding the .NET interface to new HALCON operators. This assembly is based on the C# source fileHDOTNETpackage.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.dllTo create an executable, reference the newly created assembly
Hpackage.dlland the HALCON .NET assembly as well. -
Creating new applications:
To create new application programs written in C or C++, linklibpackage.soandlibpackagec.soorlibpackagecpp.soto your objects (besideslibhalcon.soandlibhalconc.soorlibhalconcpp.soas for any HALCON application). For .NET applications, reference the assembliespackagedotnet.dllandhalcondotnet.dll.Furthermore, add the package library subdirectory
lib/$HALCONARCHto the environment variableLD_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, andlibhalconcxl.soin case of a C application).