Warning, /office/calligra/libs/README is written in an unsupported language. File is not indexed.
0001 Calligra libs is a collection of libraries for very different functionality 0002 with the common denominator that some Calligra applications depend on it. 0003 Each of the libraries have a Mainpage.dox file which is used for API docs 0004 and it should contain an overview of the library goal and scope. If you 0005 add a class you should likely read this before deciding where it goes. 0006 0007 Various details can also be found here; 0008 http://community.kde.org/Calligra/Libs 0009 0010 0011 At this point in time (early 2010) all of the libraries in here are not 0012 guarenteed to have binary or source compatibility between releases. 0013 However there is a strong push to make a subset of libraries become 0014 more used outside of Calligra and thus they need to be backwards compatible 0015 between releases. Which in effect means that we are working towards them 0016 becoming Binary and Source (and behavior) compatible between releases. 0017 0018 0019 General policies 0020 ================ 0021 0022 All code in Calligra libs that will be released shall be licensed under the 0023 terms of the GNU Library General Public License as published by the Free 0024 Software Foundation; either version 2 of the License, or any later version. 0025 0026 All libraries shall be able to compile as the first and/or only part of Calligra. 0027 Which effectively means anything in libs can not depend on another part of 0028 Calligra outside of the libs. 0029 0030 0031 Code submit policies 0032 ==================== 0033 0034 For code and files in Calligra/libs we have some rules. 0035 As Calligra is part of KDE we follow the KDE policies; 0036 http://techbase.kde.org/Policies 0037 more specifically, for all of the code under calligra/libs we follow the coding style 0038 http://techbase.kde.org/Policies/Kdelibs_Coding_Style 0039 0040 0041 Naming 0042 ====== 0043 0044 All of Calligra libs uses so called CamelCase naming for all files in the libraries. 0045 Example: KoParagraphDialog.cpp 0046 File extensions are always .cpp and .h 0047 We prefer one class per file. This is to make the filename match the class, which 0048 obviously does not work if there is more then one class in the file. 0049 When there is a private class that is not used outside the file it's ok to have it 0050 in the same file as another class. 0051 Private classes that should never be exported or used outside the library and should be 0052 placed in a header file with the extension _p.h (like KoRuler_p.h) 0053 This makes it very obvious this file is not part of the public API of Calligra. 0054 0055 0056 Namespaces and more naming 0057 ========================== 0058 0059 Calligra in general does not use namespaces, but uses a prefix for each class. 0060 Application maintainers may have a slightly different rule. 0061 0062 The libs certainly don't use namespaces and (exported) classes in the libs use 0063 the name prefix 'Ko'. 0064 This allows you to see that any class that starts with 'Ko' is from the Calligra libs. 0065 Note that this implies that the naming prefix 'Ko' is restricted to the libs, classes 0066 outside the libs are not allowed to use it. 0067 0068 Futher names are 0069 KW for Words classes 0070 KoPA for the libs/kopageapp library 0071 KPr for KPresenter 0072 0073 0074 Backwards compatibility for some libs 0075 ===================================== 0076 0077 For libraries that are going to have usage outside of Calligra they have some extra 0078 rules to make sure they are backwards compatible between releases. 0079 The list of libraries that this applies to is; 0080 * koodf 0081 * koplugin 0082 * pigment 0083 * flake 0084 * kotext 0085 0086 on top of the above list of guidelines there are some more for these that have 0087 to be taken into account when modifying them or adding new code. 0088 http://techbase.kde.org/Policies/Library_Code_Policy 0089 http://techbase.kde.org/Policies/Library_Documentation_Policy 0090 0091 Not a rule, but often used in Calligra libs is the shared-d-pointer. As this 0092 is a trick that is a bit tricky lets use this place to point to an excellent 0093 example. Make sure to use when appropriate. (ask if in doubt) 0094 http://techbase.kde.org/Policies/Library_Code_Policy/Shared_D-Pointer_Example 0095 0096 0097 Final rule, the common sense rule :) 0098 If in doubt about any code change, post a review request for your change! 0099