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.
-4. Adding sample or contrib library
------------------------------------
+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.
-5. Adding new core library
+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
library built in monolithic mode. We will assume that the new library is
called wxFoo.
-a) Add files to files.bkl FIXME
+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
+ * 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 FIXME
+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 FIXME
+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 wx-config.in to contain information about the library and needed
- linker flags:
- * Add "foo" to either CORE_BASE_LIBS or CORE_GUI_LIBS so that wxFoo is
- not treated as contrib library in monolithic build.
+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 (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)
#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")
-h) Add information about wxFoo to the manual
- FIXME - where exactly
+i) Add information about wxFoo to the manual ("Libraries list" section
+ in libs.tex).
=== EOF ===
projects / wxWidgets.git / blobdiff