diff --git a/docs/contributing/how-to-add-files-to-build-system.md b/docs/contributing/how-to-add-files-to-build-system.md index b632ddb471..dc5ff3f7fb 100644 --- a/docs/contributing/how-to-add-files-to-build-system.md +++ b/docs/contributing/how-to-add-files-to-build-system.md @@ -5,26 +5,26 @@ How to add new files and libraries to wxWidgets build system Regenerating makefiles ---------------------- -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.x installed on Unix and either use Bakefile installer or have -Python on Windows. +wxWidgets uses the legacy 0.2 branch [Bakefile](https://www.bakefile.org) to +generate native makefiles. + +Currently the latest version from legacy-0.2-branch must be used, so you need +to compile it from source, which requires Python 2 headers and libraries. 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 +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. +(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 -needs, too. See Bakefiles.bkgen for details on bakefile commands used to +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: @@ -47,9 +47,9 @@ Or monolithic wxBase: -DOFFICIAL_BUILD=0 -DUSE_HTML=0 -DUSE_OPENGL=0 -DMONOLITHIC=1 -DUSE_GUI=0 wx.bkl -It is, however, recommended to modify Bakefiles.bkgen (or -Bakefiles.local.bkgen) by means of `` and `` directives -and use bakefile_gen instead of running bakefile directly. +It is, however, recommended to modify `Bakefiles.bkgen` (or +`Bakefiles.local.bkgen)` by means of `` and `` directives +and use `bakefile_gen` instead of running bakefile directly. Bakefile files organization @@ -57,42 +57,42 @@ Bakefile files organization Makefile are generated from .bkl files ("bakefiles") from two places: - - $(wx)/build/bakefiles directory + - `$(wx)/build/bakefiles` directory - samples directories -$(wx)/build/bakefiles contains bakefiles for main library and support files +`$(wx)/build/bakefiles` contains bakefiles for main library and support files that simplify writing bakefiles for samples. Support files are: - - wxwin.py - helper functions - - common.bkl - - common_samples.bkl - - config.bkl - user-configurable build options - - make_dist.mk - implementation of "make dist" on Unix + - `wxwin.py` - helper functions + - `common.bkl` + - `common_samples.bkl` + - `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 + - `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 Adding files to existing library -------------------------------- -**UPDATE:** files.bkl is now itself partially generated from the master file - build/files. If the variable which you need to modify, according to the - instructions below, is already defined in build/files, update it there - and run build/upmake to update files.bkl. +**UPDATE:** `files.bkl` is now itself partially generated from the master file +`build/files`. If the variable which you need to modify, according to the +instructions below, is already defined in `build/files`, update it there and run +`build/upmake` to update `files.bkl`. -All files used by main libraries are listed in files.bkl. The file is +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 @@ -100,7 +100,7 @@ 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 - be present several times in files.bkl in different contexts. +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 @@ -125,7 +125,7 @@ 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). +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. @@ -133,11 +133,11 @@ The Windows resource specification should use the central .rc file: ../sample.rc -Run bakefile_gen in $(wx)/build/bakefiles to regenerate the bakefiles. +Run `bakefile_gen` in `$(wx)/build/bakefiles` to regenerate the bakefiles. -Finally commit $(wx)/build/bakefiles/make_dist.mk and all the other modified files. +Finally commit `$(wx)/build/bakefiles/make_dist.mk` and all the other modified files. -Currently we commit the generated makefiles except .dms, .vcp. +Currently we commit all the generated makefiles. Adding new core library @@ -150,21 +150,21 @@ 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. + 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. + 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). + `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`. + `ALL_BASE_SOURCES`. (You can apply different approaches to HDR and SRC variables, if e.g. headers are all common but sources are not.) @@ -174,10 +174,10 @@ a) Add files to files.bkl: 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. + 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: + libraries" section). It looks like this: $(mk.evalExpr(wxwin.mkLibName('foo'))) @@ -228,10 +228,10 @@ 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 - in libs.tex) and update docs/latex/wx/libs.dia (you need Dia for this) + 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 `#pragma comment(lib, "foo")` (for all build configuration 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. + the end of `include/wx/msw/chkconf.h`. diff --git a/docs/contributing/how-to-add-new-sample.md b/docs/contributing/how-to-add-new-sample.md index ae1c933c73..4b0388d3ff 100644 --- a/docs/contributing/how-to-add-new-sample.md +++ b/docs/contributing/how-to-add-new-sample.md @@ -10,17 +10,17 @@ samples/ with demos/ where needed). 2. "git add" the sample sources (usually based on minimal.cpp) as well. Note that unless your sample requires something special you shouldn't - add foo.rc, foo.ico, ... any more, please just reuse the generic sample.* + add foo.rc, foo.ico, ... any more, please just reuse the generic `sample.*` files in the samples subdirectory. 3. Create the makefiles: - modify samples/samples.bkl (just copy an existing line) - create foo.bkl (`sed 's/minimal/foo/g' minimal.bkl > foo.bkl` is usually - enough, but you may need to add more `` lines if your sample uses - anything not in the core lib) + enough, but you may need to add more `` lines if your sample uses + anything not in the core lib) - generate the makefiles for your sample using bakefile. For this you - need to: - - install bakefile (see http://bakefile.sf.net/) + need to: + - install bakefile (see docs/contributing/how-to-add-files-to-build-system.md) - run bakefile_gen in build/bakefiles which will regenerate all makefiles which are not up to date @@ -29,8 +29,6 @@ samples/ with demos/ where needed). or even add a `-f` to generate just the makefiles for the given compiler (run `bakefile --help` to get the list of possible values). See how-to-add-files-to-build-system.md for more information. - - currently samples/samples.dsw needs to be updated manually as it's not - generated by bakefile. 4. Modify configure.in Unix compilation: - if the sample should only be built if `wxUSE_FOO` is enabled, locate @@ -56,8 +54,7 @@ samples/ with demos/ where needed). lives in docs/doxygen/mainpages/samples.h; look at the descriptions for other samples, if you are not familiar with Doxygen. -7. Add any non-standard sample's files to build/bakefiles/make_dist.mk (the +7. Add any non-standard sample's files to `build/bakefiles/make_dist.mk` (the makefiles copies all bmp, cpp, h, ico, png, rc, xpm and makefiles by default, you only need to update it if the sample uses some other files) - and run the ./update-manifests.sh script in distrib/scripts (don't forget - to check the changes to manifests/*.rsp files in). + and run the ./update-manifests.sh script in distrib/scripts. diff --git a/docs/doxygen/mainpages/devtips.h b/docs/doxygen/mainpages/devtips.h index bd8233c573..4c38bb9fc6 100644 --- a/docs/doxygen/mainpages/devtips.h +++ b/docs/doxygen/mainpages/devtips.h @@ -136,7 +136,7 @@ For details on using makefiles, configure, and project files, please see @c "docs/xxx/install.txt" in your distribution, where @c "xxx" is the platform of interest, such as @c msw, @c gtk, @c x11, @c mac. -All wxWidgets makefiles are generated using Bakefile . +All wxWidgets makefiles are generated using Bakefile . wxWidgets also provides (in the @c "build/bakefiles/wxpresets" folder) the wxWidgets bakefile presets. These files allow you to create bakefiles for your own wxWidgets-based applications very easily.