|
|
| (10 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| = Introduction =
| | {{Moved To Community}} |
| | |
| All KDE 4 releases need to keep binary and source compatibility with KDE 4.0.0. This doesn't affect only the C++ code, but also the CMake modules installed with kdelibs (also the cmake modules of the other KDE modules ?).
| |
| | |
| == What does that mean? ==
| |
| | |
| A program which was developed against KDE 4.0.0, must also build against let's say KDE 4.5.9. The CMakeLists.txt may look like that (ignoring KDE specific stuff):
| |
| | |
| <code>
| |
| find_package(FooBar)
| |
| | |
| set(MySources main.cpp)
| |
| set(MyLinkLibs ...)
| |
| | |
| if(FOOBAR_FOUND)
| |
| add_definitions(-D_USE_FOOBAR ${FOOBAR_DEFINITIONS} )
| |
| set(MySources ${MySources} foobarwidget.cpp)
| |
| include_directories(${FOOBAR_INCLUDES})
| |
| set(MyLinkLibs ${MyLinkLibs} ${FOOBAR_LIBRARIES})
| |
|
| |
| foobar_do_stuff()
| |
| endif(FOOBAR_FOUND)
| |
| | |
| ...
| |
| add_executable(kapp ${MySources})
| |
| ...
| |
| | |
| target_link_libraries(kapp ${MyLinkLibs})
| |
| </code>
| |
| | |
| | |
| So here we have a CMakeLists.txt which uses the library/package "FooBar", you can exchange FooBar
| |
| with ANY CMake module, e.g. KDE4, Qt4, GIF, Freetype, etc.
| |
| | |
| ==In order to stay source compatible, the following has to be kept ==
| |
| | |
| ===The CMake module FindFooBar.cmake must stay available===
| |
| | |
| Otherwise CMake will fail with "could not find FindFooBar.cmake".
| |
| This means either it has to stay in the KDE module, or in the case that KDE would require a newer
| |
| version of CMake which comes with a (for KDE) usable version of that module, that the minimum required
| |
| version of CMake must ship this module (which must be fully compatible).
| |
| | |
| | |
| ===The file name of the CMake module must stay exactly the same ===
| |
| | |
| E.g. in KDE 4.0.0 we have a FindFreetype.cmake installed by kdelibs. This filename must stay
| |
| exactly the same, also the case must not change (e.g. FindFreeType.cmake).
| |
| Otherwise the same as in 1) will happen.
| |
| | |
| | |
| ===Macros coming with the module must stay compatible===
| |
| | |
| So if FindFooBar.cmake in kdelibs 4.0.0 has a macro <tt>FOOBAR_DO_STUFF()</tt>, this macro
| |
| must be available in all KDE4 versions, with exactly the same name and the arguments
| |
| supported in KDE 4.0.0 must be supported in all KDE4 versions.
| |
| It is possible to add new or alternative arguments to a macro, but the old behaviour
| |
| must stay supported.
| |
| | |
| | |
| ===Variables coming with the module must stay compatible===
| |
| | |
| In the example above several variables from FindFooBar.cmake are used:
| |
| <tt>FOOBAR_DEFINITIONS, FOOBAR_INCLUDES, FOOBAR_LIBRARIES</tt> and <tt>FOOBAR_FOUND</tt>.
| |
| At least all "public" variables (i.e. those documented in the header of the cmake
| |
| module) must be available from this module in all releases of KDE4.
| |
| This means
| |
| * their case must not change
| |
| * they must have equivalent values
| |
| | |
| This means that e.g. <tt>FOOBAR_LIBRARIES</tt> must always contain all libraries required to link to in order to use the package FooBar.
| |
| Maybe this would be in KDE 4.0.0 something like "-lfoobar -lz".
| |
| This could be changed later on to the recommended format: "/usr/lib/libfoobar.so;/usr/lib/libz.so"
| |
| It must not be changed in a way so that then additional variables would be required for successful linking.
| |
| E.g. the following change would be wrong:
| |
| <pre>
| |
| FOOBAR_LIBRARIES="/usr/lib/libfoobar.so"
| |
| FOOBAR_EXTRA_LIBRARIES="/usr/lib/libz.so"
| |
| </pre>
| |
| | |
| == What changes are possible? ==
| |
| 1) New modules can be added.
| |
| | |
| 2) New variables can be added to existing modules.
| |
| | |
| It has to be made sure that the existing ones stay working, s.a.
| |
| | |
| 3) New macros can be added.
| |
| | |
| It has to be made sure that the existing ones stay working, s.a.
| |
| If a new and better alternative to an existing macro is added, the old one may be marked as deprecated like this:
| |
| | |
| macro(OLD_SIMPLE_MACRO args...)
| |
| message(STATUS "OLD_SIMPLE_MACRO() is deprecated, use NEW_FANCY_MACRO() instead")
| |
| ...keep the macro implementation here, so the macro keeps working
| |
| endmacro(OLD_SIMPLE_MACRO)
| |
| | |
| macro(NEW_FANCY_MACRO args...)
| |
| ... new fancy implementation
| |
| endmacro(NEW_FANCY_MACRO)
| |
| | |
| | |
| 4) More arguments can be added to existing macros.
| |
| | |
| It has to be made sure that the macro stays working as it did before with the old set of arguments.
| |
