docs/tech/tn0016.txt

   1          How to add new files and libraries to wxWindows build system
   2          ============================================================
   3
   4
   5 1. Regenerating makefiles
   6 -------------------------
   7
   8 wxWindows now uses Bakefile (http://bakefile.sourceforge.net) to generate
   9 native makefiles. You must have bakefile installed if you want to regenerate
  10 the makefiles. Bakefile currently runs on Unix and Windows systems. You will
  11 need Python >= 2.2 installed on Unix and either use Bakefile installer or have
  12 Python on Windows.
  13
  14 Once you have installed Bakefile, you can easily regenerate the makefiles using
  15 the bakefile_gen tool. Run it from $(wx)/build/bakefiles directory and it will
  16 regenerate all outdated makefiles. See $(wx)/build/bakefiles/README for more
  17 details.
  18
  19 Note that it generates makefiles for samples and contrib libraries, too.
  20
  21 IMPORTANT NOTE: Don't forget to run autoconf in wxWindows root directory if
  22                 you changed any conditional variable or target condition
  23                 in .bkl files! You will know that this happened if
  24                 $(wx)/autoconf_inc.m4 content changed.
  25
  26 You can use Bakefile to generate makefiles or projects customized to your
  27 needs, too. See Bakefiles.bkgen for details on bakefile commands used to
  28 generate makefiles. For example, you can use this command to generate
  29 VC++ project files without wxUniversal configurations:
  30     bakefile -v -fmsvc6prj -o../wxmy.dsw -DRUNTIME_LIBS=dynamic
  31              -DDEBUG_INFO=default -DDEBUG_FLAG=default
  32              -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 -DUSE_ODBC=1
  33              -DMONOLITHIC=0 -DUSE_GUI=1 -DWXUNIV=0 wx.bkl
  34 Or monolithic instead of multilib (the default):
  35     bakefile -v -fmsvc6prj -o../wxmono.dsw -DRUNTIME_LIBS=dynamic
  36              -DDEBUG_INFO=default -DDEBUG_FLAG=default
  37              -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 -DUSE_ODBC=1
  38              -DMONOLITHIC=1 -DUSE_GUI=1 wx.bkl
  39 Or monolithic wxBase:
  40     bakefile -v -fmsvc6prj -o../wxBase.dsw -DRUNTIME_LIBS=dynamic
  41              -DDEBUG_INFO=default -DDEBUG_FLAG=default
  42              -DOFFICIAL_BUILD=0 -DUSE_HTML=0 -DUSE_OPENGL=0 -DUSE_ODBC=0
  43              -DMONOLITHIC=1 -DUSE_GUI=0 wx.bkl
  44
  45
  46 2. Bakefile files organization
  47 ------------------------------
  48
  49 Makefile are generated from .bkl files ("bakefiles") from three places:
  50   - $(wx)/build/bakefiles directory
  51   - $(wx)/contrib/build/* directories
  52   - samples directories
  53 $(wx)/build/bakefiles contains bakefiles for main library and support files
  54 that simplify writing bakefiles for contrib and samples.
  55
  56 Support files are:
  57   wxwin.py                - helper functions
  58   common.bkl
  59   common_samples.bkl
  60   common_contrib.bkl      - shared definitions and templates
  61   config.bkl              - user-configurable build options
  62   make_dist.mk            - implementation of "make dist" on Unix
  63
  64 Files used to build the library are:
  65   wx.bkl                  - main file
  66   files.bkl               - lists of source files
  67   monolithic.bkl          - targets for wxWin built as single big library
  68   multilib.bkl            - targets for multilib build
  69   opengl.bkl              - GL library with wxGLCanvas (this one is not
  70                             included in monolithic library for historical
  71                             reasons, so "monolithic" really means "two libs")
  72   {expat,jpeg,png,tiff,
  73    regex,zlib,odbc}.bkl   - 3rd party libraries makefiles
  74
  75
  76 3. Adding files to existing library
  77 -----------------------------------
  78
  79 All files used by main libraries are listed in files.bkl. The file is
  80 organized into variables for toolkits, platforms and libraries. The variables
  81 come in pairs: there's always FOO_SRC for source files and FOO_HDR for header
  82 files. Platform or toolkit specific files are grouped together in variable
  83 with platform or tookit name in them, e.g. BASE_WIN32_SRC, BASE_UNIX_SRC,
  84 GTK_SRC, MOTIF_SRC.
  85
  86 Note: A side effect of this toolkit-centric organization is that one file may
  87       be present several times in files.bkl in different contenxt.
  88
  89 When you are adding a file, you must put it into appropriate variable. This is
  90 easy if you are adding the file to library that is always built from same
  91 sources on all platforms (e.g. wxXml or wxXML) -- simply add the file to e.g.
  92 HTML_SRC or HTML_HDR.
  93
  94 If the file is used only on one platform and is part of wxBase, add it to
  95 BASE_{platform}_SRC/HDR. If it is used on all platforms, add it to BASE_CMN.
  96 If it is built on more than one platform but not on all of them, add the file
  97 to *all platforms that use it*!
  98
  99 If a file is not wxBase file, but GUI file, then the variables are named after
 100 toolkits/ports, not platforms. Same rules as for wxBase files apply
 101 (substitute "platform" with "toolkit"). Make sure you correctly choose between
 102 {port}_LOWLEVEL_SRC and {port}_SRC -- the former is for files used by
 103 wxUniversal, e.g. GDI classes. Files shared by all X Window System ports
 104 should be put into XWIN_LOWLEVEL_SRC.
 105
 106
 107 4. Adding sample
 108 ----------------
 109
 110 Copy the bakefile from another sample, change the ID and files accordingly.
 111 If the sample uses some data files, make sure to have <wx-data> node
 112 in the sample's bakefile (see e.g. samples/image/image.bkl for an example).
 113 Make sure to add <wx-lib> statements for all libraries from multilib build
 114 that are required by the sample.
 115
 116 Run Python script regenMakefile.py in $(wx)/build/bakefiles to update Makefile
 117 then run "make" in $(wx)/build/bakefiles directories.
 118
 119 Finally commit $(wx)/build/bakefiles/Makefile and all the other modified files.
 120
 121
 122 5. Adding contrib library
 123 -------------------------
 124
 125 Contrib library bakefiles are located in $(wx)/contrib/build/name-of-contrib
 126 directory, together with generated makefiles. Copy the bakefile from another
 127 contrib library, change the IDs and files accordingly. Note that there must be
 128 two targets for contrib wxFoo: foodll and foolib.
 129
 130 foodll definition must contain <wx-lib> statements for all libraries it
 131 depends on. WXUSINGDLL and WXMAKINGDLL_FOO must be defined and symbols from
 132 the library should use WXDLLIMPEXP_FOO defined in wxFoo's headers analogically
 133 to WXDLLIMPEXP_{BASE,CORE,HTML,...} in the main library (see 5g below for
 134 additional details).
 135
 136 Run Python script regenMakefile.py in $(wx)/build/bakefiles to update Makefile
 137 and commit $(wx)/build/bakefiles/Makefile.
 138
 139
 140 6. Adding new core library
 141 --------------------------
 142
 143 When adding new library to the core set of libraries, the files must be
 144 added to both a newly added library in multilib build and into the single
 145 library built in monolithic mode. We will assume that the new library is
 146 called wxFoo.
 147
 148 a) Add files to files.bkl:
 149    * If wxFoo builds from same files on all platforms (e.g. wxNet),
 150      add FOO_SRC and FOO_HDR variables with lists of sources and headers.
 151    * If wxFoo have no files in common (e.g. wxGL), add FOO_SRC and FOO_HDR
 152      with toolkit or platform conditions. Have a look at OPENGL_SRC for an
 153      example.
 154    * Otherwise add FOO_CMN_SRC and FOO_CMN_HDR for common files and
 155      FOO_{platform}_{SRC,HDR} or FOO_{toolkit}_{SRC,HDR} as appropriate. Add
 156      FOO_PLATFORM_{SRC,HDR} into "Define sources for specific libraries"
 157      section that is conditionally set to one of FOO_xxx_{SRC,HDR} based on
 158      target platform/toolkit (see NET_PLATFORM_SRC definition for an example).
 159      Finally, define FOO_SRC and FOO_HDR to contain both
 160      FOO_PLATFORM_{SRC,HDR} and FOO_{SRC,HDR} (see NET_SRC definition for an
 161      example).
 162    * Add FOO_HDR to ALL_GUI_HEADERS or ALL_BASE_HEADERS.
 163    * If wxFoo is wxBase library (doesn't use GUI), add FOO_SRC to
 164      ALL_BASE_SOURCES.
 165
 166    (You can apply different approaches to HDR and SRC variables, if e.g.
 167    headers are all common but sources are not.)
 168
 169    Note that the conditions can only test for equality, due to limitations of
 170    native make tools.
 171
 172 b) Modify bakefile system in build/bakefiles/ to recognize wxFoo:
 173    * Add 'foo' to MAIN_LIBS and LIBS_NOGUI or LIBS_GUI (depending on whether
 174      the library depends on wxCore or not) to wxwin.py file.
 175    * Add the library to DEPS_TABLE in wxwin.py
 176    * Add WXLIB_FOO definition to common.bkl (into the "Names of component
 177      libraries" section). It looks like this:
 178        <set var="WXLIB_FOO">
 179           <if cond="MONOLITHIC=='0'">$(mk.evalExpr(wxwin.mkLibName('foo')))</if>
 180        </set>
 181
 182 c) Add files to monolithic build: it's enough to add FOO_SRC to MONOLIB_GUI_SRC
 183    or MONOLIB_SRC, depending on whether wxFoo uses GUI or not.
 184
 185 d) Add files to multilib build: add foolib and foodll targets. Don't use
 186    wxBase targets as the template, use e.g. wxXML or wxHTML. Make sure
 187    WXMAKINGDLL_FOO is defined in foodll.
 188
 189 e) Regenerate all makefiles (don't forget to run autoconf)
 190
 191 f) Update configure.in and wx-config.in to contain information about
 192    the library and needed linker flags:
 193    * Add "foo" to either CORE_BASE_LIBS or CORE_GUI_LIBS in configure.in so
 194      that wxFoo is not treated as contrib library in monolithic build.
 195    * If wxFoo links against additional libraries, add neccessary linker
 196      flags and libraries to ldflags_foo and ldlibs_foo variables in
 197      wx-config.in (both are optional).
 198
 199 g) Update defs.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add
 200    #define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in defs.h)
 201    and to define WXDLLIMPEXP_FOO and WXDLLIMPEXP_DATA_FOO. You can copy
 202    e.g. WXDLLIMPEXP_NET definition, it is something like this:
 203         #ifdef WXMAKINGDLL_NET
 204             #define WXDLLIMPEXP_NET WXEXPORT
 205             #define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type
 206         #elif defined(WXUSINGDLL)
 207             #define WXDLLIMPEXP_NET WXIMPORT
 208             #define WXDLLIMPEXP_DATA_NET(type) WXIMPORT type
 209         #else // not making nor using DLL
 210             #define WXDLLIMPEXP_NET
 211             #define WXDLLIMPEXP_DATA_NET(type) type
 212         #endif
 213    Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions.
 214
 215 h) Add this code to one of wxFoo's files (the more often used, the better):
 216       // DLL options compatibility check:
 217       #include "wx/app.h"
 218       WX_CHECK_BUILD_OPTIONS("wxFoo")
 219
 220 i) Add information about wxFoo to the manual ("Libraries list" section
 221    in libs.tex).
 222
 223
 224 === EOF ===
 225
 226 Version: $Id$