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