Development/Tutorials/Creating Libraries (zh CN) - Revision history

AnneW at 13:31, 18 July 2012

2012-07-18T13:31:01Z

Zguangyu0000: /* 想构建系统中添加库 */

2012-07-11T06:25:16Z

‎想构建系统中添加库

Neverendingo: Text replace - "`" to ""`


2011-06-29T21:10:06Z
Text replace - "<code mode=cppqt>" to "<syntaxhighlight lang="cpp-qt">"

				
				
				
				
			
			← Older revision
			Revision as of 21:10, 29 June 2011
			
Line 194:
Line 194:
    
  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:   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:
− <code mode=cppqt> + <syntaxhighlight lang="cpp-qt">
       KGlobal::locale()->insertCatalog( "libmyshare" );        KGlobal::locale()->insertCatalog( "libmyshare" );
  </syntaxhighlight>   </syntaxhighlight>



Neverendingo: Text replace - "" to ""

2011-06-29T20:59:59Z
Text replace - "<code cpp>" to "<syntaxhighlight lang="cpp">"

				
				
				
				
			
			← Older revision
			Revision as of 20:59, 29 June 2011
			
Line 58:
Line 58:
  For this add a file myshared_export.h to the directory of the library, containing:   For this add a file myshared_export.h to the directory of the library, containing:
    
− <code cpp> + <syntaxhighlight lang="cpp">
  #ifndef MYSHARED_EXPORT_H   #ifndef MYSHARED_EXPORT_H
  #define MYSHARED_EXPORT_H   #define MYSHARED_EXPORT_H



Neverendingo: Text replace - "" to ""
2011-06-29T20:44:57Z
Text replace - "</code>" to "</syntaxhighlight>"

				
				
				
				
			
			← Older revision
			Revision as of 20:44, 29 June 2011
			
Line 38:
Line 38:
    
  install( TARGETS myshared  ${INSTALL_TARGETS_DEFAULT_ARGS} )   install( TARGETS myshared  ${INSTALL_TARGETS_DEFAULT_ARGS} )
− </code> + </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.   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 80:
Line 80:
    
  #endif   #endif
− </code> + </syntaxhighlight>
    
  This macro code defines the tag <tt>MYSHARED_EXPORT</tt> for the library.   This macro code defines the tag <tt>MYSHARED_EXPORT</tt> for the library.
Line 91:
Line 91:
  // class declaration as usual   // class declaration as usual
  };   };
− </code> + </syntaxhighlight>
    
  And the same with the other class:   And the same with the other class:
Line 100:
Line 100:
  // class declaration as usual   // class declaration as usual
  };   };
− </code> + </syntaxhighlight>
    
  {{warning|   {{warning|
Line 120:
Line 120:
     COMPONENT Devel      COMPONENT Devel
  )   )
− </code> + </syntaxhighlight>
    
  Of course also myshared_export.h is installed, as it gets included by the headers of both classes.   Of course also myshared_export.h is installed, as it gets included by the headers of both classes.
Line 129:
Line 129:
  #include <myshared/myaclass.h>   #include <myshared/myaclass.h>
  #include <myshared/mybclass.h>   #include <myshared/mybclass.h>
− </code> + </syntaxhighlight>
    
  ==获得正确的版本号==   ==获得正确的版本号==
Line 140:
Line 140:
     PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}      PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}
  )   )
− </code> + </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.   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 175:
Line 175:
  set(GENERIC_LIB_VERSION "4.1.0")   set(GENERIC_LIB_VERSION "4.1.0")
  set(GENERIC_LIB_SOVERSION "4")   set(GENERIC_LIB_SOVERSION "4")
− </code> + </syntaxhighlight>
    
    
Line 190:
Line 190:
  # fetch all strings in source code files   # fetch all strings in source code files
  $XGETTEXT `find . -name \*.cc -o -name \*.cpp -o -name \*.h` -o $podir/libmyshare.pot   $XGETTEXT `find . -name \*.cc -o -name \*.cpp -o -name \*.h` -o $podir/libmyshare.pot
− </code> + </syntaxhighlight>
  So all strings will end in a catalog named <tt>libmyshare</tt>.   So all strings will end in a catalog named <tt>libmyshare</tt>.
    
Line 196:
Line 196:
  <code mode=cppqt>   <code mode=cppqt>
       KGlobal::locale()->insertCatalog( "libmyshare" );        KGlobal::locale()->insertCatalog( "libmyshare" );
− </code> + </syntaxhighlight>
  The method <tt>insertCatalog()</tt> will load the translated strings in the current language from the catalog named <tt>libmyshare</tt>.   The method <tt>insertCatalog()</tt> will load the translated strings in the current language from the catalog named <tt>libmyshare</tt>.
    
Line 223:
Line 223:
  kde4_add_library( myutils  STATIC ${myutils_LIB_SRCS} )   kde4_add_library( myutils  STATIC ${myutils_LIB_SRCS} )
    
− </code> + </syntaxhighlight>
    
  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.   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 235:
Line 235:
  add_subdirectory( myutils )   add_subdirectory( myutils )
  add_subdirectory( mygui )   add_subdirectory( mygui )
− </code> + </syntaxhighlight>
    
  This inclusion can be done recursively, so in a subdirectory you can add again the subsubdirectory.   This inclusion can be done recursively, so in a subdirectory you can add again the subsubdirectory.
Line 248:
Line 248:
  # also the ones needed by your static libraries mygui and myutils   # also the ones needed by your static libraries mygui and myutils
  )   )
− </code> + </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.   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.



Neverendingo: Text replace - "" to ""

2011-06-29T20:44:40Z
Text replace - "<code>" to "<syntaxhighlight lang="text">"

				
				
				
				
			
			← Older revision
			Revision as of 20:44, 29 June 2011
			
Line 16:
Line 16:
    
  You also need a file CMakeLists.txt in the same directory as the source files:     You also need a file CMakeLists.txt in the same directory as the source files:  
− <code> + <syntaxhighlight lang="text">
  include_directories(   include_directories(
  # any directories needed by the sources of the library   # any directories needed by the sources of the library
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:   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:
    
− <code> + <syntaxhighlight lang="text">
  set( myshared_LIB_HDRS   set( myshared_LIB_HDRS
     myshared_export.h      myshared_export.h
Line 136:
Line 136:
    
  As you already saw above the version of your library is defined by <tt>set_target_properties()</tt>:   As you already saw above the version of your library is defined by <tt>set_target_properties()</tt>:
− <code> + <syntaxhighlight lang="text">
  set_target_properties( myshared   set_target_properties( myshared
     PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}      PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}
Line 172:
Line 172:
    
  E.g. for KDE 4.1.0 these variables are defined in kdelibs/cmake/modules/KDE4Defaults.cmake with   E.g. for KDE 4.1.0 these variables are defined in kdelibs/cmake/modules/KDE4Defaults.cmake with
− <code> + <syntaxhighlight lang="text">
  set(GENERIC_LIB_VERSION "4.1.0")   set(GENERIC_LIB_VERSION "4.1.0")
  set(GENERIC_LIB_SOVERSION "4")   set(GENERIC_LIB_SOVERSION "4")
Line 184:
Line 184:
  You mark the strings to be translated [[Development/Tutorials/Localization/i18n|as usual]]. And     You mark the strings to be translated [[Development/Tutorials/Localization/i18n|as usual]]. And  
  [[Development/Tutorials/Localization/i18n Build Systems|like you do with programs]] you have to add a shell script named <tt>Messages.sh</tt> in the toplevel directory of your shared library to collect all the strings, e.g.:   [[Development/Tutorials/Localization/i18n Build Systems|like you do with programs]] you have to add a shell script named <tt>Messages.sh</tt> in the toplevel directory of your shared library to collect all the strings, e.g.:
− <code> + <syntaxhighlight lang="text">
  #!bin/sh   #!bin/sh
  # fetch all strings in files that are not source code   # fetch all strings in files that are not source code
Line 209:
Line 209:
  E.g. for the subdirectory "myutils" "myutils/CMakeLists.txt" looks like:   E.g. for the subdirectory "myutils" "myutils/CMakeLists.txt" looks like:
    
− <code> + <syntaxhighlight lang="text">
  include_directories(   include_directories(
  # only as needed for the sources of this directory/library   # only as needed for the sources of this directory/library
Line 232:
Line 232:
    
  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.   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> + <syntaxhighlight lang="text">
  add_subdirectory( myutils )   add_subdirectory( myutils )
  add_subdirectory( mygui )   add_subdirectory( mygui )
Line 241:
Line 241:
  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.:   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> + <syntaxhighlight lang="text">
  target_link_libraries( myprogram   target_link_libraries( myprogram
     mygui      mygui



Neverendingo: Text replace - "" to ""

2011-06-29T20:28:18Z
Text replace - "<code cppqt>" to "<syntaxhighlight lang="cpp-qt">"

				
				
				
				
			
			← Older revision
			Revision as of 20:28, 29 June 2011
			
Line 85:
Line 85:
    
  Now you prepare all classes by adding a include for the header with the library's export tag and putting the export tag defined above in front of the class name, like this:   Now you prepare all classes by adding a include for the header with the library's export tag and putting the export tag defined above in front of the class name, like this:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  #include "myshared_export.h"   #include "myshared_export.h"
    
Line 94:
Line 94:
    
  And the same with the other class:   And the same with the other class:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  #include "myshared_export.h"   #include "myshared_export.h"
    
Line 126:
Line 126:
  External KDE code which should use the library's classes and functions now can include the headers by the lines:   External KDE code which should use the library's classes and functions now can include the headers by the lines:
    
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  #include <myshared/myaclass.h>   #include <myshared/myaclass.h>
  #include <myshared/mybclass.h>   #include <myshared/mybclass.h>



Tangooricha at 04:09, 13 September 2009
2009-09-13T04:09:35Z


				
				
				
				
			
			← Older revision
			Revision as of 04:09, 13 September 2009
			
Line 1:
Line 1:
  {{Template:I18n/Language Navigation Bar|Development/Tutorials/Creating Libraries}}   {{Template:I18n/Language Navigation Bar|Development/Tutorials/Creating Libraries}}
    
− ==Abstract== + ==摘要==
    
  If a part of your code could be used by more than one software module, like other programs or plugins, you should put that part in a shared library. This tutorial tells how to add the library to the buildsystem and how to prepare the source code.   If a part of your code could be used by more than one software module, like other programs or plugins, you should put that part in a shared library. This tutorial tells how to add the library to the buildsystem and how to prepare the source code.
    
− ==Separating the code== + ==分离代码==
    
  It is good practise to put all source files for a library in a separate directory.   It is good practise to put all source files for a library in a separate directory.
Line 13:
Line 13:
  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''.   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== + ==想构建系统中添加库==
    
  You also need a file CMakeLists.txt in the same directory as the source files:     You also need a file CMakeLists.txt in the same directory as the source files:  
Line 48:
Line 48:
  And <tt>install()</tt> moves the library to a place where it can be loaded.   And <tt>install()</tt> moves the library to a place where it can be loaded.
    
− ==Declaring exported classes and methods== + ==声明导出的类和方法==
    
  If a library gets compiled, all functions or class methods it offers get listed as so called symbols in a table. Each symbol points to the offset in the library where the corresponding code can be found.   If a library gets compiled, all functions or class methods it offers get listed as so called symbols in a table. Each symbol points to the offset in the library where the corresponding code can be found.
Line 106:
Line 106:
    
    
− ==Enabling others to compile using your library== + ==使其他程序能使用你的库==
    
  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:   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:
Line 131:
Line 131:
  </code>   </code>
    
− ==Getting the version numbers right== + ==获得正确的版本号==
    
  By installing the header files you are releasing your library officially. External code will rely on the interfaces declared by the headers. So you need to care for binary and behaviour compatibility if developing your library further. Any changes in the next release should be reflected in the version number, so external code gets compiled, linked and run with the matching version of your library.   By installing the header files you are releasing your library officially. External code will rely on the interfaces declared by the headers. So you need to care for binary and behaviour compatibility if developing your library further. Any changes in the next release should be reflected in the version number, so external code gets compiled, linked and run with the matching version of your library.
Line 144:
Line 144:
  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.   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.
    
− === Defining the development version === + === 定义开发版本 ===
  The value of <tt>VERSION</tt> defines the development state of your library. It is good practice to use a pattern "major.minor.patch-level".   The value of <tt>VERSION</tt> defines the development state of your library. It is good practice to use a pattern "major.minor.patch-level".
  For each release you need to update or reset the different parts:   For each release you need to update or reset the different parts:
Line 152:
Line 152:
  This version ends in the name of the resulting library file, e.g. on Linux "libmyshared.so.2.3.10" or "libmyshared.2.3.10.so".   This version ends in the name of the resulting library file, e.g. on Linux "libmyshared.so.2.3.10" or "libmyshared.2.3.10.so".
    
− === Defining the ABI version === + === 定义ABI版本 ===
  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-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.
    
Line 168:
Line 168:
  }}   }}
    
− ===Using the generic versions=== + ===使用通用的版本===
  If you are developing your library inside a normal KDE module, e.g. kdeutils, and all new versions of your library are only released together with the usual KDE releases, of course following the policies regarding ABI as demanded, you do not need to take care of the versioning yourself. Just use the generic variables <tt>${GENERIC_LIB_VERSION}</tt> and <tt>${GENERIC_LIB_SOVERSION}</tt> as shown above. Using the generic version numbers also helps to identify a version of your library by the general KDE version.   If you are developing your library inside a normal KDE module, e.g. kdeutils, and all new versions of your library are only released together with the usual KDE releases, of course following the policies regarding ABI as demanded, you do not need to take care of the versioning yourself. Just use the generic variables <tt>${GENERIC_LIB_VERSION}</tt> and <tt>${GENERIC_LIB_SOVERSION}</tt> as shown above. Using the generic version numbers also helps to identify a version of your library by the general KDE version.
    
Line 178:
Line 178:
    
    
− ==Making localization work== + ==本地化工作==
    
  If your shared library contains translations you have to help a little so a program which uses your library can make use of them.   If your shared library contains translations you have to help a little so a program which uses your library can make use of them.
Line 199:
Line 199:
  The method <tt>insertCatalog()</tt> will load the translated strings in the current language from the catalog named <tt>libmyshare</tt>.   The method <tt>insertCatalog()</tt> will load the translated strings in the current language from the catalog named <tt>libmyshare</tt>.
    
− ==Organizing your program code with static libraries== + ==用静态库组织你的程序代码==
  Sharing code with others is one reason to separate code into libraries.   Sharing code with others is one reason to separate code into libraries.
  Another reason is the need to organize a large code base.   Another reason is the need to organize a large code base.



Tangooricha: Created page with '{{Template:I18n/Language Navigation Bar|Development/Tutorials/Creating Libraries}}  ==Abstract==  If a part of your code could be used by more than one software module, like othe...'
2009-09-13T04:02:18Z
Created page with '{{Template:I18n/Language Navigation Bar|Development/Tutorials/Creating Libraries}}  ==Abstract==  If a part of your code could be used by more than one software module, like othe...'
New page
{{Template:I18n/Language Navigation Bar|Development/Tutorials/Creating Libraries}}



==Abstract==



If a part of your code could be used by more than one software module, like other programs or plugins, you should put that part in a shared library. This tutorial tells how to add the library to the buildsystem and how to prepare the source code.



==Separating the code==



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 '''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==



You also need a file CMakeLists.txt in the same directory as the source files: 

<code>

include_directories(

# any directories needed by the sources of the library

)



set( myshared_LIB_SRCS

  myaclass.cpp

  mybclass.cpp

  myinternalcclass.cpp

  myinternaldclass.cpp

)



kde4_add_library( myshared  SHARED ${myshared_LIB_SRCS} )



target_link_libraries( myshared

  ${KDE4_KDECORE_LIBS}

)

set_target_properties( myshared

  PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}

)



install( TARGETS myshared  ${INSTALL_TARGETS_DEFAULT_ARGS} )

</code>



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.



Like with a program, other libraries that are used have to be defined with <tt>target_link_libraries()</tt>.



The version number of the library is set by <tt>set_target_properties()</tt>.



And <tt>install()</tt> moves the library to a place where it can be loaded.



==Declaring exported classes and methods==



If a library gets compiled, all functions or class methods it offers get listed as so called symbols in a table. Each symbol points to the offset in the library where the corresponding code can be found.



Adding also functions or class methods to the table which are not intended to be called from the outside is of no use. It just bloats the table and asks others to make calls to them against your will. For the library myshared you do not want to add the methods of the classes MyInternalCClass and MyInternalDClass.



In the KDE buildsystem you need to put explicitly a tag to all the classes and functions which the library should provide externally. This tag has to have a different name for each library.



For this add a file myshared_export.h to the directory of the library, containing:



<code cpp>

#ifndef MYSHARED_EXPORT_H

#define MYSHARED_EXPORT_H



// needed for KDE_EXPORT and KDE_IMPORT macros

#include <kdemacros.h>



#ifndef MYSHARED_EXPORT

# if defined(MAKE_MYSHARED_LIB)

   // We are building this library

#  define MYSHARED_EXPORT KDE_EXPORT

# else

   // We are using this library

#  define MYSHARED_EXPORT KDE_IMPORT

# endif

#endif



# ifndef MYSHARED_EXPORT_DEPRECATED

#  define MYSHARED_EXPORT_DEPRECATED KDE_DEPRECATED MYSHARED_EXPORT

# endif



#endif

</code>



This macro code defines the tag <tt>MYSHARED_EXPORT</tt> for the library.



Now you prepare all classes by adding a include for the header with the library's export tag and putting the export tag defined above in front of the class name, like this:

<code cppqt>

#include "myshared_export.h"



class MYSHARED_EXPORT MyAClass {

// class declaration as usual

};

</code>



And the same with the other class:

<code cppqt>

#include "myshared_export.h"



class MYSHARED_EXPORT MyBClass {

// class declaration as usual

};

</code>



{{warning|

Beware that header-only classes, even additionally based on templates, must not have an export tag. Their methods do not end as any symbol in the library. Instead all machine code is created on demand in the external calling software, if compiled.}}





==Enabling others to compile using your library==



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:



<code>

set( myshared_LIB_HDRS

  myshared_export.h

  myaclass.h

  mybclass.h

)

install( FILES ${myshared_LIB_HDRS}

  DESTINATION ${INCLUDE_INSTALL_DIR}/myshared

  COMPONENT Devel

)

</code>



Of course also myshared_export.h is installed, as it gets included by the headers of both classes.



External KDE code which should use the library's classes and functions now can include the headers by the lines:



<code cppqt>

#include <myshared/myaclass.h>

#include <myshared/mybclass.h>

</code>



==Getting the version numbers right==



By installing the header files you are releasing your library officially. External code will rely on the interfaces declared by the headers. So you need to care for binary and behaviour compatibility if developing your library further. Any changes in the next release should be reflected in the version number, so external code gets compiled, linked and run with the matching version of your library.



As you already saw above the version of your library is defined by <tt>set_target_properties()</tt>:

<code>

set_target_properties( myshared

  PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}

)

</code>



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.



=== Defining the development version ===

The value of <tt>VERSION</tt> defines the development state of your library. It is good practice to use a pattern "major.minor.patch-level".

For each release you need to update or reset the different parts:

* Only bug fixes added: increase the patch-level, e.g. 2.3.10 -> 2.3.11

* New functionality added, while keeping the old functionality: increase the minor number, reset the patch-level, e.g. 2.3.10 -> 2.4.0

* Binary or behaviour changes of old functionality, regardless of any new functionality: increase the major number, reset the minor number and the patch-level, e.g. 2.3.10 -> 3.0.0

This version ends in the name of the resulting library file, e.g. on Linux "libmyshared.so.2.3.10" or "libmyshared.2.3.10.so".



=== 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.



{{tip|

If you follow the rules given above for the <tt>VERSION</tt> version, the value of <tt>SOVERSION</tt> will of course match the major number of it. So with a <tt>VERSION</tt> of 2.3.10 the <tt>SOVERSION</tt> value would be 2. But this is no necessity.}}



This version ends in a reference with ABI versioning to the resulting library file, e.g. on Linux in the symbolic link "libmyshared.so.2", which points to the real library file. These versioned references are used by the dynamic linker to load the version of the library with the matching ABI variant to a running executable. Executables which are linked to a shared library have a note which ABI variant of these libray is needed.



{{warning|

This concept of ABI versioning breaks if the executable got linked to a newer version of the library (e.g. 2.4.0) which is backward-compatible to older versions (all 2.0-3.*) but additionally offers new functionality that also gets used by the executable.



Because conforming to the concept the older versions have the same ABI version like the newer one (e.g. 2). So if only an older version of the library is installed (e.g. 2.1.8) the executable is still started as the tested prerequisites (ABI version) are matched, but it will crash due to the missing functionality if the library gets finally loaded.



In a compilation-from-sourcecode-based system this just should not happen, unless you downgrade a library again. And in a package-based system dependency checks on de-/installations of packages which also care for the <tt>VERSION</tt> version should prevent this. So you might also forget about this problem.

}}



===Using the generic versions===

If you are developing your library inside a normal KDE module, e.g. kdeutils, and all new versions of your library are only released together with the usual KDE releases, of course following the policies regarding ABI as demanded, you do not need to take care of the versioning yourself. Just use the generic variables <tt>${GENERIC_LIB_VERSION}</tt> and <tt>${GENERIC_LIB_SOVERSION}</tt> as shown above. Using the generic version numbers also helps to identify a version of your library by the general KDE version.



E.g. for KDE 4.1.0 these variables are defined in kdelibs/cmake/modules/KDE4Defaults.cmake with

<code>

set(GENERIC_LIB_VERSION "4.1.0")

set(GENERIC_LIB_SOVERSION "4")

</code>





==Making localization work==



If your shared library contains translations you have to help a little so a program which uses your library can make use of them.



You mark the strings to be translated [[Development/Tutorials/Localization/i18n|as usual]]. And 

[[Development/Tutorials/Localization/i18n Build Systems|like you do with programs]] you have to add a shell script named <tt>Messages.sh</tt> in the toplevel directory of your shared library to collect all the strings, e.g.:

<code>

#!bin/sh

# fetch all strings in files that are not source code

$EXTRACTRC `find . -name \*.rc -o -name \*.ui -o -name \*.kcfg` >> rc.cpp

# fetch all strings in source code files

$XGETTEXT `find . -name \*.cc -o -name \*.cpp -o -name \*.h` -o $podir/libmyshare.pot

</code>

So all strings will end in a catalog named <tt>libmyshare</tt>.



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:

<code mode=cppqt>

    KGlobal::locale()->insertCatalog( "libmyshare" );

</code>

The method <tt>insertCatalog()</tt> will load the translated strings in the current language from the catalog named <tt>libmyshare</tt>.



==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 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. 



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.

}}



It is not uncommon for a static library to become a shared dynamic library later in development, if the code in the library proves to be complete and useful for others.

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

	==摘要==		==摘要==