From b6e20cff8cf7625e4bb5e2fc69522d731dd4bea2 Mon Sep 17 00:00:00 2001 From: =?utf8?q?V=C3=A1clav=20Slav=C3=ADk?= Date: Thu, 31 Jul 2003 09:53:49 +0000 Subject: [PATCH] finished documentation on modifying new build system git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@22402 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/tech/tn0016.txt | 149 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 142 insertions(+), 7 deletions(-) diff --git a/docs/tech/tn0016.txt b/docs/tech/tn0016.txt index 5805e0cc6f..86ddfccf2d 100644 --- a/docs/tech/tn0016.txt +++ b/docs/tech/tn0016.txt @@ -5,20 +5,131 @@ 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 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 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 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. + 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 + +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 node +in the sample's bakefile (see e.g. samples/image/image.bkl for an example). +Make sure to add 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 +and commit $(wx)/build/bakefiles/Makefile. + + +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 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. -5. Adding new core library +6. Adding new core library -------------------------- When adding new library to the core set of libraries, the files must be @@ -26,7 +137,27 @@ 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 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_HEADERS + + (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 @@ -37,9 +168,12 @@ b) Modify bakefile system in build/bakefiles/ to recognize wxFoo: $(mk.evalExpr(wxwin.mkLibName('foo'))) -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) @@ -65,8 +199,9 @@ g) Update defs.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add #define WXDLLIMPEXP_NET #define WXDLLIMPEXP_DATA_NET(type) type #endif + Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions. -h) Add information about wxFoo to the manual +i) Add information about wxFoo to the manual FIXME - where exactly -- 2.45.2