Difference between revisions of "Documentation/DevGuide/WritingUNO/C++/Building and Testing C++ Components"

Latest revision as of 14:41, 24 December 2020

Build Process

For details about building component code, see the gnu makefile. It uses a number of platform dependent variables used in the SDK that are included from <SDK>/settings/settings.mk. For simplicity, details are omitted here, and the build process is just sketched in eight steps:

1. The UNOIDL compiler compiles the .idl file some.idl into an urd file.
2. The resulting binary .urd files are merged into a new simple_component.rdb.
3. The tool xml2cmp parses the xml component description simple_component.xml for types needed for compiling. This file describes the service implementation(s) for deployment, such as the purpose of the implementation(s) and used types. Visit https://www.openoffice.org/udk/common/man/module_description.html for details about the syntax of these XML files.
4. The types parsed in step 3 are passed to cppumaker, which generates the appropriate header pairs into the output include directory using simple_component.rdb and the Apache OpenOffice type library types.rdb that is stored in the program directory of your Apache OpenOffice installation.

For your own component you can simplify step 3 and 4, and pass the types used by your component to cppumaker using the -T option.

5. The source files service1_impl.cxx and service2_impl.cxx are compiled.
6. The shared library is linked out of object files, linking dynamically to the UNO base libraries sal, cppu and cppuhelper. The shared library's name is libsimple_component.so on Unix and simple_component.dll on Windows.

In general, the shared library component should limit its exports to only the above mentioned functions (prefixed with component_) to avoid symbol clashes on Unix. In addition, for the gnu gcc3 C++ compiler, it is necessary to export the RTTI symbols of exceptions, too.

7. The shared library component is registered into simple_component.rdb. This can also be done manually running

 $ regcomp -register -r simple_component.rdb -c simple_component.dll

Test Registration and Use

The component's registry simple_component.rdb has entries for the registered service implementations. If the library is registered successfully, run:

 $ regview simple_component.rdb

The result should look similar to the following:

 /
   / UCR
     / my_module
       / XSomething
 
         ... interface information ...
 
   / IMPLEMENTATIONS
     / my_module.my_sc_impl.MyService2
       / UNO
         / ACTIVATOR
           Value: Type = RG_VALUETYPE_STRING
                  Size = 34
                  Data = "com.sun.star.loader.SharedLibrary"
 
         / SERVICES
           / my_module.MyService2
         / LOCATION
           Value: Type = RG_VALUETYPE_STRING
                  Size = 21
                  Data = "simple_component.dll"
 
     / my_module.my_sc_impl.MyService1
       / UNO
         / ACTIVATOR
           Value: Type = RG_VALUETYPE_STRING
                  Size = 34
                  Data = "com.sun.star.loader.SharedLibrary"
 
         / SERVICES
           / my_module.MyService1
         / LOCATION
           Value: Type = RG_VALUETYPE_STRING
                  Size = 21
                  Data = "simple_component.dll"
 
   / SERVICES
     / my_module.MyService1
       Value: Type = RG_VALUETYPE_STRINGLIST
              Size = 40
              Len = 1
              Data = 0 = "my_module.my_sc_impl.MyService1"
 
     / my_module.MyService2
       Value: Type = RG_VALUETYPE_STRINGLIST
              Size = 40
              Len = 1
              Data = 0 = "my_module.my_sc_impl.MyService2"

Apache OpenOffice recognizes registry files being inserted into the unorc file (on Unix, uno.ini on Windows) in the program directory of your Apache OpenOffice installation. Extend the types and services in that file by simple_component.rdb. The given file has to be an absolute file URL, but if the rdb is copied to the Apache OpenOffice program directory, a $ORIGIN macro can be used, as shown in the following unorc file:

 [Bootstrap]
 UNO_TYPES=$ORIGIN/types.rdb $ORIGIN/simple_component.rdb
 UNO_SERVICES=$ORIGIN/services.rdb $ORIGIN/simple_component.rdb

Second, when running Apache OpenOffice, extend the PATH (Windows) or LD_LIBRARY_PATH (Unix), including the output path of the build, so that the loader finds the component. If the shared library is copied to the program directory or a link is created inside the program directory (Unix only), do not extend the path.

Launching the test component inside a Apache OpenOffice Basic script is simple to do, as shown in the following code:

  Sub Main
 
      REM calling service1 impl
      mgr = getProcessServiceManager()
      o = mgr.createInstance("my_module.MyService1")
      MsgBox o.methodOne("foo")
      MsgBox o.dbg_supportedInterfaces
 
      REM calling service2 impl
      dim args( 0 )
      args( 0 ) = "foo"
      o = mgr.createInstanceWithArguments("my_module.MyService2", args())
      MsgBox o.methodOne("bar")
      MsgBox o.dbg_supportedInterfaces
 
  End Sub

This procedure instantiates the service implementations and performs calls on their interfaces. The return value of the methodOne() call is brought up in message boxes. The Basic object property dbg_supportedInterfaces retrieves its information through the com.sun.star.lang.XTypeProvider interfaces of the objects.