documented how to handle C++ exceptions in wxWindows

[wxWidgets.git] / docs / tech / tn0016.txt

         How to add new files and libraries to wxWindows build system
         ============================================================


1. Regenerating makefiles
-------------------------

wxWindows now uses Bakefile (http://bakefile.sourceforge.net) to generate
native makefiles. You must have bakefile installed if you want to regenerate
the makefiles. Bakefile currently runs on Unix and Windows systems. You will
need Python >= 2.2 installed on Unix and either use Bakefile installer or have
Python on Windows.

Once you have installed Bakefile, you can easily regenerate the makefiles using
the bakefile_gen tool. Run it from $(wx)/build/bakefiles directory and it will
regenerate all outdated makefiles. See $(wx)/build/bakefiles/README for more
details.

Note that it generates makefiles for samples and contrib libraries, too.

IMPORTANT NOTE: Don't forget to run autoconf in wxWindows root directory if
                you changed any conditional variable or target condition
                in .bkl files! You will know that this happened if
                $(wx)/autoconf_inc.m4 content changed.

You can use Bakefile to generate makefiles or projects customized to your
needs, too. See Bakefiles.bkgen for details on bakefile commands used to
generate makefiles. For example, you can use this command to generate
VC++ project files without wxUniversal configurations:
    bakefile -v -fmsvc6prj -o../wxmy.dsw -DRUNTIME_LIBS=dynamic
             -DDEBUG_INFO=default -DDEBUG_FLAG=default
             -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 -DUSE_ODBC=1
             -DMONOLITHIC=0 -DUSE_GUI=1 -DWXUNIV=0 wx.bkl
Or monolithic instead of multilib (the default):
    bakefile -v -fmsvc6prj -o../wxmono.dsw -DRUNTIME_LIBS=dynamic
             -DDEBUG_INFO=default -DDEBUG_FLAG=default
             -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 -DUSE_ODBC=1
             -DMONOLITHIC=1 -DUSE_GUI=1 wx.bkl
Or monolithic wxBase:
    bakefile -v -fmsvc6prj -o../wxBase.dsw -DRUNTIME_LIBS=dynamic
             -DDEBUG_INFO=default -DDEBUG_FLAG=default
             -DOFFICIAL_BUILD=0 -DUSE_HTML=0 -DUSE_OPENGL=0 -DUSE_ODBC=0
             -DMONOLITHIC=1 -DUSE_GUI=0 wx.bkl


2. Bakefile files organization
------------------------------

Makefile are generated from .bkl files ("bakefiles") from three places:
  - $(wx)/build/bakefiles directory
  - $(wx)/contrib/build/* directories
  - samples directories
$(wx)/build/bakefiles contains bakefiles for main library and support files
that simplify writing bakefiles for contrib and samples.

Support files are:
  wxwin.py                - helper functions
  common.bkl
  common_samples.bkl
  common_contrib.bkl      - shared definitions and templates
  config.bkl              - user-configurable build options
  make_dist.mk            - implementation of "make dist" on Unix

Files used to build the library are:
  wx.bkl                  - main file
  files.bkl               - lists of source files
  monolithic.bkl          - targets for wxWin built as single big library
  multilib.bkl            - targets for multilib build
  opengl.bkl              - GL library with wxGLCanvas (this one is not
                            included in monolithic library for historical
                            reasons, so "monolithic" really means "two libs")
  {expat,jpeg,png,tiff,
   regex,zlib,odbc}.bkl   - 3rd party libraries makefiles


3. Adding files to existing library
-----------------------------------

All files used by main libraries are listed in files.bkl. The file is
organized into variables for toolkits, platforms and libraries. The variables
come in pairs: there's always FOO_SRC for source files and FOO_HDR for header
files. Platform or toolkit specific files are grouped together in variable
with platform or tookit name in them, e.g. BASE_WIN32_SRC, BASE_UNIX_SRC,
GTK_SRC, MOTIF_SRC.

Note: A side effect of this toolkit-centric organization is that one file may
      be present several times in files.bkl in different contenxt.

When you are adding a file, you must put it into appropriate variable. This is
easy if you are adding the file to library that is always built from same
sources on all platforms (e.g. wxXml or wxXML) -- simply add the file to e.g.
HTML_SRC or HTML_HDR.

If the file is used only on one platform and is part of wxBase, add it to
BASE_{platform}_SRC/HDR. If it is used on all platforms, add it to BASE_CMN.
If it is built on more than one platform but not on all of them, add the file
to *all platforms that use it*!

If a file is not wxBase file, but GUI file, then the variables are named after
toolkits/ports, not platforms. Same rules as for wxBase files apply
(substitute "platform" with "toolkit"). Make sure you correctly choose between
{port}_LOWLEVEL_SRC and {port}_SRC -- the former is for files used by
wxUniversal, e.g. GDI classes. Files shared by all X Window System ports
should be put into XWIN_LOWLEVEL_SRC.


4. Adding sample
----------------

Copy the bakefile from another sample, change the ID and files accordingly.
If the sample uses some data files, make sure to have <wx-data> node
in the sample's bakefile (see e.g. samples/image/image.bkl for an example).
Make sure to add <wx-lib> statements for all libraries from multilib build
that are required by the sample.

Run Python script regenMakefile.py in $(wx)/build/bakefiles to update Makefile
then run "make" in $(wx)/build/bakefiles directories.

Finally commit $(wx)/build/bakefiles/Makefile and all the other modified files.


5. Adding contrib library
-------------------------

Contrib library bakefiles are located in $(wx)/contrib/build/name-of-contrib
directory, together with generated makefiles. Copy the bakefile from another
contrib library, change the IDs and files accordingly. Note that there must be
two targets for contrib wxFoo: foodll and foolib.

foodll definition must contain <wx-lib> statements for all libraries it
depends on. WXUSINGDLL and WXMAKINGDLL_FOO must be defined and symbols from
the library should use WXDLLIMPEXP_FOO defined in wxFoo's headers analogically
to WXDLLIMPEXP_{BASE,CORE,HTML,...} in the main library (see 5g below for
additional details).

Run Python script regenMakefile.py in $(wx)/build/bakefiles to update Makefile
and commit $(wx)/build/bakefiles/Makefile.


6. Adding new core library
--------------------------

When adding new library to the core set of libraries, the files must be
added to both a newly added library in multilib build and into the single
library built in monolithic mode. We will assume that the new library is
called wxFoo.

a) Add files to files.bkl:
   * If wxFoo builds from same files on all platforms (e.g. wxNet),
     add FOO_SRC and FOO_HDR variables with lists of sources and headers.
   * If wxFoo have no files in common (e.g. wxGL), add FOO_SRC and FOO_HDR
     with toolkit or platform conditions. Have a look at OPENGL_SRC for an
     example.
   * Otherwise add FOO_CMN_SRC and FOO_CMN_HDR for common files and
     FOO_{platform}_{SRC,HDR} or FOO_{toolkit}_{SRC,HDR} as appropriate. Add
     FOO_PLATFORM_{SRC,HDR} into "Define sources for specific libraries"
     section that is conditionally set to one of FOO_xxx_{SRC,HDR} based on
     target platform/toolkit (see NET_PLATFORM_SRC definition for an example).
     Finally, define FOO_SRC and FOO_HDR to contain both
     FOO_PLATFORM_{SRC,HDR} and FOO_{SRC,HDR} (see NET_SRC definition for an
     example).
   * Add FOO_HDR to ALL_GUI_HEADERS or ALL_BASE_HEADERS. 
   * If wxFoo is wxBase library (doesn't use GUI), add FOO_SRC to
     ALL_BASE_SOURCES.

   (You can apply different approaches to HDR and SRC variables, if e.g.
   headers are all common but sources are not.)

   Note that the conditions can only test for equality, due to limitations of
   native make tools.

b) Modify bakefile system in build/bakefiles/ to recognize wxFoo:
   * Add 'foo' to MAIN_LIBS and LIBS_NOGUI or LIBS_GUI (depending on whether
     the library depends on wxCore or not) to wxwin.py file.
   * Add the library to DEPS_TABLE in wxwin.py
   * Add WXLIB_FOO definition to common.bkl (into the "Names of component
     libraries" section). It looks like this:
       <set var="WXLIB_FOO">
          <if cond="MONOLITHIC=='0'">$(mk.evalExpr(wxwin.mkLibName('foo')))</if>
       </set>

c) Add files to monolithic build: it's enough to add FOO_SRC to MONOLIB_GUI_SRC
   or MONOLIB_SRC, depending on whether wxFoo uses GUI or not.

d) Add files to multilib build: add foolib and foodll targets. Don't use
   wxBase targets as the template, use e.g. wxXML or wxHTML. Make sure
   WXMAKINGDLL_FOO is defined in foodll.

e) Regenerate all makefiles (don't forget to run autoconf)

f) Update configure.in and wx-config.in to contain information about
   the library and needed linker flags:
   * Add "foo" to either CORE_BASE_LIBS or CORE_GUI_LIBS in configure.in so
     that wxFoo is not treated as contrib library in monolithic build.
   * If wxFoo links against additional libraries, add neccessary linker
     flags and libraries to ldflags_foo and ldlibs_foo variables in
     wx-config.in (both are optional).

g) Update defs.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add
   #define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in defs.h)
   and to define WXDLLIMPEXP_FOO and WXDLLIMPEXP_DATA_FOO. You can copy
   e.g. WXDLLIMPEXP_NET definition, it is something like this:
        #ifdef WXMAKINGDLL_NET
            #define WXDLLIMPEXP_NET WXEXPORT
            #define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type
        #elif defined(WXUSINGDLL)
            #define WXDLLIMPEXP_NET WXIMPORT
            #define WXDLLIMPEXP_DATA_NET(type) WXIMPORT type
        #else // not making nor using DLL
            #define WXDLLIMPEXP_NET
            #define WXDLLIMPEXP_DATA_NET(type) type
        #endif
   Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions.

h) Add this code to one of wxFoo's files (the more often used, the better):
      // DLL options compatibility check:
      #include "wx/app.h"
      WX_CHECK_BUILD_OPTIONS("wxFoo")

i) Add information about wxFoo to the manual ("Libraries list" section
   in libs.tex).


=== EOF ===

Version: $Id$