Development/Tutorials/Creating Libraries - Revision history

AnneW at 18:33, 12 July 2012

2012-07-12T18:33:52Z

Rakuco: /* Defining the ABI version */ Fix typo

2011-11-05T01:39:16Z

‎Defining the ABI version: Fix typo

Icwiener: Fix syntax highlighting.

2011-06-30T11:57:01Z

Fix syntax highlighting.

Icwiener: Fix syntax highlighting.

2011-06-27T13:45:43Z

Fix syntax highlighting.

Show changes

Rakuco: /* Separating the code */ Added some formatting

2009-05-18T01:56:33Z

‎Separating the code: Added some formatting

Frinring: Added: Rough version how to support translations

2008-04-16T18:27:54Z

Added: Rough version how to support translations

Frinring: /* Getting the version numbers right */

2008-04-12T23:19:20Z

‎Getting the version numbers right

Frinring: include_directories() added to example

2008-04-12T23:15:27Z

include_directories() added to example

Frinring: added: all "exported" in static libs; static becoming shared not uncommon

2008-04-12T22:32:44Z

added: all "exported" in static libs; static becoming shared not uncommon

Frinring: Add first draft of "Organizing your program code with static libraries"

2008-04-12T22:22:51Z

Add first draft of "Organizing your program code with static libraries"

← Older revision		Revision as of 18:33, 12 July 2012
Line 1:		Line 1:
−	~~{{Template:I18n/Language Navigation Bar\|Development/Tutorials/Creating Libraries}}~~
−
	==Abstract==		==Abstract==

@@ Line 153: / Line 153: @@
 === Defining the ABI version ===
-The value of <tt>SOVERSION</tt> defines the ABI variant of your library. It is a single always increasing integer, numbering the versions with non-backward-compatibel changes. So if you release a new version with some binary or behaviour changes you need to increase this version number by one, e.g. 2->3, otherwise you keep it.
+The value of <tt>SOVERSION</tt> defines the ABI variant of your library. It is a single always increasing integer, numbering the versions with non-backward-compatible changes. So if you release a new version with some binary or behaviour changes you need to increase this version number by one, e.g. 2->3, otherwise you keep it.
 {{tip|

@@ Line 16: / Line 16: @@
 You also need a file CMakeLists.txt in the same directory as the source files:
-<pre>
+<syntaxhighlight lang="cmake">
 include_directories(
 # any directories needed by the sources of the library
@@ Line 38: / Line 38: @@
 install( TARGETS myshared  ${INSTALL_TARGETS_DEFAULT_ARGS} )
-</pre>
+</syntaxhighlight>
 The instructions are similar to the ones for a program. But instead of calling <tt>kde4_add_executable()</tt> you use <tt>kde4_add_library()</tt> to register  the library <tt>myshared</tt>. The parameter <tt>SHARED</tt> is needed as this declares the library is a shared one, not a static.
@@ Line 110: / Line 110: @@
 You need also tell the buildsystem to install the header files. Without this external code can not build, as it can not include the files and thus the class and methods declarations of your library. You do this by adding to the library's CMakeLists.txt:
-<pre>
+<syntaxhighlight lang="cmake">
 set( myshared_LIB_HDRS
    myshared_export.h
@@ Line 120: / Line 120: @@
    COMPONENT Devel
+)
-</pre>
+</syntaxhighlight>
 Of course also myshared_export.h is installed, as it gets included by the headers of both classes.
@@ Line 136: / Line 136: @@
 As you already saw above the version of your library is defined by <tt>set_target_properties()</tt>:
-<pre>
+<syntaxhighlight lang="cmake">
 set_target_properties( myshared
    PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}
+)
-</pre>
+</syntaxhighlight>
 So there are two different kind of versions, the development version <tt>VERSION</tt> and the ABI version <tt>SOVERSION</tt>. Both will be explained now.
@@ Line 172: / Line 172: @@
 E.g. for KDE 4.1.0 these variables are defined in kdelibs/cmake/modules/KDE4Defaults.cmake with
-<pre>
+<syntaxhighlight lang="cmake">
 set(GENERIC_LIB_VERSION "4.1.0")
 set(GENERIC_LIB_SOVERSION "4")
-</pre>
+</syntaxhighlight>
@@ Line 195: / Line 195: @@
 While for programs and most plugins the translations are loaded automatically, for shared libraries you have to do it manually. You do so by adding in the program after the creation of the <tt>KApplication</tt> or <tt>KCoreApplication</tt> instance the line:
 <syntaxhighlight lang="cpp-qt">
-    KGlobal::locale()->insertCatalog( "libmyshare" );
+KGlobal::locale()->insertCatalog( "libmyshare" );
 </syntaxhighlight>
 The method <tt>insertCatalog()</tt> will load the translated strings in the current language from the catalog named <tt>libmyshare</tt>.
@@ Line 209: / Line 209: @@
 E.g. for the subdirectory "myutils" "myutils/CMakeLists.txt" looks like:
-<pre>
+<syntaxhighlight lang="cmake">
 include_directories(
 # only as needed for the sources of this directory/library
@@ Line 222: / Line 222: @@
 kde4_add_library( myutils  STATIC ${myutils_LIB_SRCS} )
+</syntaxhighlight>
-</pre>
 The instructions are similar to the ones for a shared library. In the call <tt>kde4_add_library()</tt> you just use the parameter <tt>STATIC</tt> instead to declare the library is a static one.
@@ Line 232: / Line 231: @@
 To have all the local CMakeLists.txt files get used by the build system you need to add each subdirectory to the CMakeLists.txt file in the upper directory, with the call <tt>add_subdirectory()</tt>, e.g.
-<pre>
+<syntaxhighlight lang="cmake">
 add_subdirectory( myutils )
 add_subdirectory( mygui )
-</pre>
+</syntaxhighlight>
 This inclusion can be done recursively, so in a subdirectory you can add again the subsubdirectory.
@@ Line 241: / Line 240: @@
 Finally you need to tell the buildsystem to also use the static libraries to construct the complete program. You do so by including their names in the <tt>target_link_libraries()</tt> call for the program. There you also add any not already listed shared library which is used by code in your static libraries, as told above. So to construct the program myprogram using the static libraries mygui and myutils you write the CMakeLists.txt like e.g.:
-<pre>
+<syntaxhighlight lang="cmake">
 target_link_libraries( myprogram
    mygui
@@ Line 248: / Line 247: @@
 # also the ones needed by your static libraries mygui and myutils
+)
-</pre>
+</syntaxhighlight>
 Make sure that you list those libraries, static or shared, which are also used by other libraries in the list below these, e.g. if mygui uses myutils, first list mygui, then myutils, as in the example above.

@@ Line 9: / Line 9: @@
 It is good practise to put all source files for a library in a separate directory.
-This tutorial assumes you want to create a shared library named <tt>myshare</tt>, which contains the classes MyAClass and MyBClass. Both classes use internally the classes MyInternalCClass and MyInternalDClass, but these are not found in their public interfaces.
+This tutorial assumes you want to create a shared library named '''myshare''', which contains the classes '''MyAClass''' and '''MyBClass'''. Both classes use internally the classes '''MyInternalCClass''' and '''MyInternalDClass''', but these are not found in their public interfaces.
-−
-The classes are declared and defined in the files myaclass.h, myaclass.cpp, mybclass.h, mybclass.cpp, myinternalcclass.h, myinternalcclass.cpp, myinternaldclass.h, and myinternaldclass.cpp.
 ==Adding the library to the buildsystem==

@@ Line 177: / Line 177: @@
 set(GENERIC_LIB_SOVERSION "4")
 </code>
 ==Organizing your program code with static libraries==

@@ Line 18: / Line 18: @@
 You also need a file CMakeLists.txt in the same directory as the source files:
 <code>
 set( myshared_LIB_SRCS
    myaclass.cpp
@@ Line 44: / Line 48: @@
 And <tt>install()</tt> moves the library to a place where it can be loaded.
 ==Declaring exported classes and methods==

@@ Line 204: / Line 204: @@
 The instructions are similar to the ones for a shared library. In the call <tt>kde4_add_library()</tt> you just use the parameter <tt>STATIC</tt> instead to declare the library is a static one.
-This library is only used as an intermediate product in the total build process. So you neither need to set a version number with <tt>set_target_properties()</tt> or declare at this point other libraries to link against with <tt>target_link_libraries()</tt>, like you do with a shared library. And you do not install anything, neither the lib or any header files. You declare any dynamic libraries used by it at another place, see below.
+This library is only used as an intermediate product in the total build process. So you neither need to set a version number with <tt>set_target_properties()</tt> or declare at this point other libraries to link against with <tt>target_link_libraries()</tt>, like you do with a shared library. And you do not install anything, neither the lib or any header files. You also do not mark exported classes or functions, all will be available to external code. You declare any dynamic libraries used by the library at another place, see below.
 With <tt>include_directories()</tt> you also have to list the include directories needed for the source files in the directory, and only these. So you get more control with regard to dependencies than with one big central CMakeLists.txt file.
@@ Line 235: / Line 235: @@
 This restriction is due to the fact that the linker utilities on most platforms supported only import those parts of static libraries into the end product which are referenced by the other code in the product, not simply everything. Which is useful, if the product is a program. But it isn't useful for the product dynamic library. If a function "foo()" from the static library is not used by the other code in the shared library this function will not be found in resulting shared library product. Yet third party code linking to this shared library might expect the function if it is defined as exported. Which creates a problem.
 }}

← Older revision		Revision as of 22:22, 12 April 2008
Line 174:		Line 174:
	set(GENERIC_LIB_SOVERSION "4")		set(GENERIC_LIB_SOVERSION "4")
	</code>		</code>
		+
		+
		+	==Organizing your program code with static libraries==
		+	Sharing code with others is one reason to separate code into libraries.
		+	Another reason is the need to organize a large code base.
		+
		+	A useful approach to give a structure to code is to separate the source files in different subdirectories, each subdirectory containing only code for a certain domain, e.g. a subdirectory "utils" for all utility classes or "gui" for all gui related code.
		+
		+	Instead of one big central CMakeLists.txt file you also use an own CMakeLists.txt file per subdirectory, which is also placed in that subdirectory. In each of these CMakeLists.txt files you advise the build system to construct a separate package of the compiled sources in the given directory, a so called convenience library or, in technical terms, static library.
		+
		+	E.g. for the subdirectory "myutils" "myutils/CMakeLists.txt" looks like:
		+
		+	<code>
		+	include_directories(
		+	# only as needed for the sources of this directory/library
		+	)
		+
		+	set( myutils_LIB_SRCS
		+	myutilaclass.cpp
		+	myutilbclass.cpp
		+	myinternalutilcclass.cpp
		+	myinternalutildclass.cpp
		+	)
		+
		+	kde4_add_library( myutils STATIC ${myutils_LIB_SRCS} )
		+
		+	</code>
		+
		+	The instructions are similar to the ones for a shared library. In the call <tt>kde4_add_library()</tt> you just use the parameter <tt>STATIC</tt> instead to declare the library is a static one.
		+
		+	This library is only used as an intermediate product in the total build process. So you neither need to set a version number with <tt>set_target_properties()</tt> or declare at this point other libraries to link against with <tt>target_link_libraries()</tt>, like you do with a shared library. And you do not install anything, neither the lib or any header files. You declare any dynamic libraries used by it at another place, see below.
		+
		+	With <tt>include_directories()</tt> you also have to list the include directories needed for the source files in the directory, and only these. So you get more control with regard to dependencies than with one big central CMakeLists.txt file.
		+
		+	To have all the local CMakeLists.txt files get used by the build system you need to add each subdirectory to the CMakeLists.txt file in the upper directory, with the call <tt>add_subdirectory()</tt>, e.g.
		+	<code>
		+	add_subdirectory( myutils )
		+	add_subdirectory( mygui )
		+	</code>
		+
		+	This inclusion can be done recursively, so in a subdirectory you can add again the subsubdirectory.
		+
		+	Finally you need to tell the buildsystem to also use the static libraries to construct the complete program. You do so by including their names in the <tt>target_link_libraries()</tt> call for the program. There you also add any not already listed shared library which is used by code in your static libraries, as told above. So to construct the program myprogram using the static libraries mygui and myutils you write the CMakeLists.txt like e.g.:
		+
		+	<code>
		+	target_link_libraries( myprogram
		+	mygui
		+	myutils
		+	# and all needed dynamic libraries, like the KDE ones and else,
		+	# also the ones needed by your static libraries mygui and myutils
		+	)
		+	</code>
		+
		+	Make sure that you list those libraries, static or shared, which are also used by other libraries in the list below these, e.g. if mygui uses myutils, first list mygui, then myutils, as in the example above.
		+
		+
		+	{{warning\|
		+	The buildsystem up to KDE 4.1 supports the use of static libraries only for programs, not for shared libraries. So use this structuring method only for programs.
		+
		+	This restriction is due to the fact that the linker utilities on most platforms supported only import those parts of static libraries into the end product which are referenced by the other code in the product, not simply everything. Which is useful, if the product is a program. But it isn't useful for the product dynamic library. If a function "foo()" from the static library is not used by the other code in the shared library this function will not be found in resulting shared library product. Yet third party code linking to this shared library might expect the function if it is defined as exported. Which creates a problem.
		+	}}