Make _() and friends safe to call from any thread.

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

diff --git a/docs/tech/tn0016.txt b/docs/tech/tn0016.txt
index 9f2d9896d7ccd50858c83fc3091fe526cf61e5ad..90af1d09ae22d4c86288d101a136fd5f34a4c892 100644 (file)
--- a/docs/tech/tn0016.txt
+++ b/docs/tech/tn0016.txt
@@ -1,79 +1,66 @@
-         How to add new files and libraries to wxWindows build system
+         How to add new files and libraries to wxWidgets build system

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

-wxWindows now uses Bakefile (http://bakefile.sourceforge.net) to generate
+wxWidgets 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
 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 makefile in $(wx)/build/bakefiles directory. The makefile uses Unix make
-syntax and works on Unix or using either Borland Make or GNU Make (including
-native Win32 port called mingw32-make from http://www.mingw.org/) on Windows.
-It is possible that other Windows make utilities work as well, but it wasn't
-tested. "make clean" only works on Unix or Cygwin or MSYS emulation layer on
-Windows.
-
-You can use following commands when generating the makefiles (must be run from
-$(wx)/build/bakefiles directory):
-
-make <filename>           generates one makefile (e.g. "make ../makefile.gcc")
-make all                  regenerates all makefiles that are out of date
-make library              only makefiles for the main library
-make <compiler>           only makefiles for given compiler; possible values
-                          are "borland", "watcom", "mingw", "autoconf", "msvc"
-                          and "mvsc6prj" (Visual C++ project files)
-make clean                deletes all generated files (Unix shell only)
-
-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.
+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, too.
+
+IMPORTANT NOTE: Don't forget to run autoconf in wxWidgets root directory
+                (after running Bakefile) 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
 
 You can use Bakefile to generate makefiles or projects customized to your

-needs, too. See Makefile for details on bakefile commands used to generate
-makefiles. For example, you can use this command to generate VC++ project
-files without wxUniversal configurations (you can find needed flags in
-DSWFLAGS variable of build/bakefiles/Makefile):
+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
     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
+             -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=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
              -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
+             -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=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
              -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
+             -DOFFICIAL_BUILD=0 -DUSE_HTML=0 -DUSE_OPENGL=0

              -DMONOLITHIC=1 -DUSE_GUI=0 wx.bkl
              -DMONOLITHIC=1 -DUSE_GUI=0 wx.bkl

+It is, however, recommended to modify Bakefiles.bkgen (or
+Bakefiles.local.bkgen) by means of <add-flags> and <del-flags> directives
+and use bakefile_gen instead of running bakefile directly.

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

-Makefile are generated from .bkl files ("bakefiles") from three places:
+Makefile are generated from .bkl files ("bakefiles") from two places:

   - $(wx)/build/bakefiles directory
   - $(wx)/build/bakefiles directory

-  - $(wx)/contrib/build/* directories

   - samples directories
 $(wx)/build/bakefiles contains bakefiles for main library and support files
   - samples directories
 $(wx)/build/bakefiles contains bakefiles for main library and support files

-that simplify writing bakefiles for contrib and samples.
+that simplify writing bakefiles for samples.

 
 Support files are:
   wxwin.py                - helper functions
   common.bkl
   common_samples.bkl
 
 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
   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 used to build the library are:
   wx.bkl                  - main file


@@ -94,11 +81,11 @@ 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
 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,
+with platform or toolkit 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
 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.
+      be present several times in files.bkl in different contexts.

 
 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
 
 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


@@ -127,31 +114,18 @@ 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.
 
 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.
+The Windows resource specification should use the central .rc file:

 
 

+        <win32-res>../sample.rc</win32-res>

 
 

-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.
+Run bakefile_gen in $(wx)/build/bakefiles to regenerate the bakefiles.

 
 

-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).
+Finally commit $(wx)/build/bakefiles/make_dist.mk and all the other modified files.

 
 

-Run Python script regenMakefile.py in $(wx)/build/bakefiles to update Makefile
-and commit $(wx)/build/bakefiles/Makefile.
+Currently we commit the generated makefiles except .dms, .vcp.

 
 
 
 

-6. Adding new core library
+5. Adding new core library

 --------------------------
 
 When adding new library to the core set of libraries, the files must be
 --------------------------
 
 When adding new library to the core set of libraries, the files must be


@@ -173,8 +147,9 @@ a) Add files to files.bkl:
      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).
      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_HEADERS (or ALL_BASE_HEADERS if wxFoo is not GUI
-     component). 
+   * 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.)
 
    (You can apply different approaches to HDR and SRC variables, if e.g.
    headers are all common but sources are not.)


@@ -183,35 +158,36 @@ a) Add files to files.bkl:
    native make tools.
 
 b) Modify bakefile system in build/bakefiles/ to recognize wxFoo:
    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
+   * 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.
      the library depends on wxCore or not) to wxwin.py file.

+   * Add extra libraries needed by wxFoo (if any) to EXTRALIBS 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>
 
    * 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.
+c) Modify monolithic.bkl to 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.
+d) Modify multilib.bkl to 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:
 
 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
+   * Add "foo" to either STD_BASE_LIBS or STD_GUI_LIBS in configure.in.
+   * If wxFoo links against additional libraries, add necessary linker

      flags and libraries to ldflags_foo and ldlibs_foo variables in
      wx-config.in (both are optional).
 
      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:
+g) Update dlimpexp.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add
+   #define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in
+   dlimpexp.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
         #ifdef WXMAKINGDLL_NET
             #define WXDLLIMPEXP_NET WXEXPORT
             #define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type


@@ -222,6 +198,7 @@ g) Update defs.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add
             #define WXDLLIMPEXP_NET
             #define WXDLLIMPEXP_DATA_NET(type) type
         #endif
             #define WXDLLIMPEXP_NET
             #define WXDLLIMPEXP_DATA_NET(type) type
         #endif

+   Don't forget to add WXDLLIMPEXP_FWD_FOO definitions too.

    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):
    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):


@@ -230,9 +207,13 @@ h) Add this code to one of wxFoo's files (the more often used, the better):
       WX_CHECK_BUILD_OPTIONS("wxFoo")
 
 i) Add information about wxFoo to the manual ("Libraries list" section
       WX_CHECK_BUILD_OPTIONS("wxFoo")
 
 i) Add information about wxFoo to the manual ("Libraries list" section

-   in libs.tex).
+   in libs.tex) and update docs/latex/wx/libs.dia (you need Dia for this)
+   to show the dependencies of the new library.

 
 

+j) Also please add 4 #pragma comment(lib, "foo") (for Unicode/ANSI
+   Release/Debug combinations) to the file include/msvc/wx/setup.h and
+   add a check for WXMAKINGDLL_FOO to the test whether we're building a DLL at
+   the end of include/wx/msw/chkconf.h.

 
 === EOF ===
 
 
 === EOF ===
 

-Version: $Id$