docs/tech/tn0016.txt

   1          How to add new files and libraries to wxWidgets build system
   2          ============================================================
   3
   4
   5 1. Regenerating makefiles
   6 -------------------------
   7
   8 wxWidgets 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, too.
  20
  21 IMPORTANT NOTE: Don't forget to run autoconf in wxWidgets root directory
  22                 (after running Bakefile) if you changed any conditional
  23                 variable or target condition in .bkl files! You will know that
  24                 this happened if $(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 It is, however, recommended to modify Bakefiles.bkgen (or
  45 Bakefiles.local.bkgen) by means of <add-flags> and <del-flags> directives
  46 and use bakefile_gen instead of running bakefile directly.
  47
  48
  49 2. Bakefile files organization
  50 ------------------------------
  51
  52 Makefile are generated from .bkl files ("bakefiles") from two places:
  53   - $(wx)/build/bakefiles directory
  54   - samples directories
  55 $(wx)/build/bakefiles contains bakefiles for main library and support files
  56 that simplify writing bakefiles for samples.
  57
  58 Support files are:
  59   wxwin.py                - helper functions
  60   common.bkl
  61   common_samples.bkl
  62   config.bkl              - user-configurable build options
  63   make_dist.mk            - implementation of "make dist" on Unix
  64
  65 Files used to build the library are:
  66   wx.bkl                  - main file
  67   files.bkl               - lists of source files
  68   monolithic.bkl          - targets for wxWin built as single big library
  69   multilib.bkl            - targets for multilib build
  70   opengl.bkl              - GL library with wxGLCanvas (this one is not
  71                             included in monolithic library for historical
  72                             reasons, so "monolithic" really means "two libs")
  73   {expat,jpeg,png,tiff,
  74    regex,zlib,odbc}.bkl   - 3rd party libraries makefiles
  75
  76
  77 3. Adding files to existing library
  78 -----------------------------------
  79
  80 All files used by main libraries are listed in files.bkl. The file is
  81 organized into variables for toolkits, platforms and libraries. The variables
  82 come in pairs: there's always FOO_SRC for source files and FOO_HDR for header
  83 files. Platform or toolkit specific files are grouped together in variable
  84 with platform or toolkit name in them, e.g. BASE_WIN32_SRC, BASE_UNIX_SRC,
  85 GTK_SRC, MOTIF_SRC.
  86
  87 Note: A side effect of this toolkit-centric organization is that one file may
  88       be present several times in files.bkl in different contexts.
  89
  90 When you are adding a file, you must put it into appropriate variable. This is
  91 easy if you are adding the file to library that is always built from same
  92 sources on all platforms (e.g. wxXml or wxXML) -- simply add the file to e.g.
  93 HTML_SRC or HTML_HDR.
  94
  95 If the file is used only on one platform and is part of wxBase, add it to
  96 BASE_{platform}_SRC/HDR. If it is used on all platforms, add it to BASE_CMN.
  97 If it is built on more than one platform but not on all of them, add the file
  98 to *all platforms that use it*!
  99
 100 If a file is not wxBase file, but GUI file, then the variables are named after
 101 toolkits/ports, not platforms. Same rules as for wxBase files apply
 102 (substitute "platform" with "toolkit"). Make sure you correctly choose between
 103 {port}_LOWLEVEL_SRC and {port}_SRC -- the former is for files used by
 104 wxUniversal, e.g. GDI classes. Files shared by all X Window System ports
 105 should be put into XWIN_LOWLEVEL_SRC.
 106
 107
 108 4. Adding sample
 109 ----------------
 110
 111 Copy the bakefile from another sample, change the ID and files accordingly.
 112 If the sample uses some data files, make sure to have <wx-data> node
 113 in the sample's bakefile (see e.g. samples/image/image.bkl for an example).
 114 Make sure to add <wx-lib> statements for all libraries from multilib build
 115 that are required by the sample.
 116
 117 The Windows resource specification should use the central .rc file:
 118
 119         <win32-res>../sample.rc</win32-res>
 120
 121 Run bakefile_gen in $(wx)/build/bakefiles to regenerate the bakefiles.
 122
 123 Finally commit $(wx)/build/bakefiles/make_dist.mk and all the other modified files.
 124
 125 Currently we commit the generated makefiles except .dms, .vcp.
 126
 127
 128 5. Adding new core library
 129 --------------------------
 130
 131 When adding new library to the core set of libraries, the files must be
 132 added to both a newly added library in multilib build and into the single
 133 library built in monolithic mode. We will assume that the new library is
 134 called wxFoo.
 135
 136 a) Add files to files.bkl:
 137    * If wxFoo builds from same files on all platforms (e.g. wxNet),
 138      add FOO_SRC and FOO_HDR variables with lists of sources and headers.
 139    * If wxFoo have no files in common (e.g. wxGL), add FOO_SRC and FOO_HDR
 140      with toolkit or platform conditions. Have a look at OPENGL_SRC for an
 141      example.
 142    * Otherwise add FOO_CMN_SRC and FOO_CMN_HDR for common files and
 143      FOO_{platform}_{SRC,HDR} or FOO_{toolkit}_{SRC,HDR} as appropriate. Add
 144      FOO_PLATFORM_{SRC,HDR} into "Define sources for specific libraries"
 145      section that is conditionally set to one of FOO_xxx_{SRC,HDR} based on
 146      target platform/toolkit (see NET_PLATFORM_SRC definition for an example).
 147      Finally, define FOO_SRC and FOO_HDR to contain both
 148      FOO_PLATFORM_{SRC,HDR} and FOO_{SRC,HDR} (see NET_SRC definition for an
 149      example).
 150    * Add FOO_HDR to ALL_GUI_HEADERS or ALL_BASE_HEADERS.
 151    * If wxFoo is wxBase library (doesn't use GUI), add FOO_SRC to
 152      ALL_BASE_SOURCES.
 153
 154    (You can apply different approaches to HDR and SRC variables, if e.g.
 155    headers are all common but sources are not.)
 156
 157    Note that the conditions can only test for equality, due to limitations of
 158    native make tools.
 159
 160 b) Modify bakefile system in build/bakefiles/ to recognize wxFoo:
 161    * Add 'foo' to MAIN_LIBS and LIBS_NOGUI or LIBS_GUI (depending on whether
 162      the library depends on wxCore or not) to wxwin.py file.
 163    * Add extra libraries needed by wxFoo (if any) to EXTRALIBS in wxwin.py
 164    * Add WXLIB_FOO definition to common.bkl (into the "Names of component
 165      libraries" section). It looks like this:
 166        <set var="WXLIB_FOO">
 167           <if cond="MONOLITHIC=='0'">$(mk.evalExpr(wxwin.mkLibName('foo')))</if>
 168        </set>
 169
 170 c) Modify monolithic.bkl to add files to monolithic build: it's enough to add
 171    FOO_SRC to MONOLIB_GUI_SRC or MONOLIB_SRC, depending on whether wxFoo uses
 172    GUI or not.
 173
 174 d) Modify multilib.bkl to add files to multilib build: add foolib and foodll
 175    targets. Don't use wxBase targets as the template, use e.g. wxXML or wxHTML.
 176    Make sure WXMAKINGDLL_FOO is defined in foodll.
 177
 178 e) Regenerate all makefiles (don't forget to run autoconf)
 179
 180 f) Update configure.in and wx-config.in to contain information about
 181    the library and needed linker flags:
 182    * Add "foo" to either STD_BASE_LIBS or STD_GUI_LIBS in configure.in.
 183    * If wxFoo links against additional libraries, add necessary linker
 184      flags and libraries to ldflags_foo and ldlibs_foo variables in
 185      wx-config.in (both are optional).
 186
 187 g) Update dlimpexp.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add
 188    #define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in
 189    dlimpexp.h) and to define WXDLLIMPEXP_FOO and WXDLLIMPEXP_DATA_FOO. You
 190    can copy e.g. WXDLLIMPEXP_NET definition, it is something like this:
 191         #ifdef WXMAKINGDLL_NET
 192             #define WXDLLIMPEXP_NET WXEXPORT
 193             #define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type
 194         #elif defined(WXUSINGDLL)
 195             #define WXDLLIMPEXP_NET WXIMPORT
 196             #define WXDLLIMPEXP_DATA_NET(type) WXIMPORT type
 197         #else // not making nor using DLL
 198             #define WXDLLIMPEXP_NET
 199             #define WXDLLIMPEXP_DATA_NET(type) type
 200         #endif
 201    Don't forget to add WXDLLIMPEXP_FWD_FOO definitions too.
 202    Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions.
 203
 204 h) Add this code to one of wxFoo's files (the more often used, the better):
 205       // DLL options compatibility check:
 206       #include "wx/app.h"
 207       WX_CHECK_BUILD_OPTIONS("wxFoo")
 208
 209 i) Add information about wxFoo to the manual ("Libraries list" section
 210    in libs.tex) and update docs/latex/wx/libs.dia (you need Dia for this)
 211    to show the dependencies of the new library.
 212
 213 j) Also please add 4 #pragma comment(lib, "foo") (for Unicode/ANSI
 214    Release/Debug combinations) to the file include/msvc/wx/setup.h and
 215    add a check for WXMAKINGDLL_FOO to the test whether we're building a DLL at
 216    the end of include/wx/msw/chkconf.h.
 217
 218 === EOF ===
 219
 220 Version: $Id$