docs/tech/tn0021.txt

   1                How to add a new wxUSE_XXX preprocessor constant
   2                ================================================
   3
   4 0. Purpose
   5 ----------
   6
   7 Detailed description of what needs to be done when you want to add a new
   8 wxUSE_XXX compilation flag. The text below assumes you need new wxUSE_FOO.
   9
  10
  11 1. Overview
  12 -----------
  13
  14 wxWidgets uses wxUSE_XXX macros for conditionally compiling in (or not)
  15 optional components. In general, whenever a new non critical (i.e. not
  16 absolutely required by important parts of the library) class Foo is added it
  17 should use its own wxUSE_FOO compilation flag.
  18
  19 wxUSE_FOO must be always defined and have value of 0 or 1. Be careful with
  20 testing for it in wx/foo.h: don't do it at the very beginning of the file
  21 because then wxUSE_FOO would be not defined at all if the user directly
  22 includes wx/foo.h, include "wx/defs.h" before testing for wxUSE_FOO.
  23
  24
  25 2. Required files update
  26 ------------------------
  27
  28 Assuming wxUSE_FOO is used on all platforms, the following must be done:
  29
  30 a) update include/wx/setup_inc.h
  31
  32    This file contains all common wxUSE_XXXs, and is used to update wxMSW, wxMac
  33    setup.h and Unix setup.h.in using build/update-setup-h. Please try to add
  34    the new define in a logical place (i.e. near any related ones) and write a
  35    detailed comment explaining what does it do and why would you want to turn
  36    it on/off. Choose the appropriate default value: this should be usually 1
  37    but can be 0 if there are some problems preventing the use of Foo by default
  38    (e.g. it requires installation of some non standard 3rd party libraries).
  39    After changing this file, run the update-setup-h script (this is probably
  40    better done on a Unix machine although it should work under Cygwin too).
  41
  42 b) update other setup.h files
  43
  44    Currently include/wx/univ/setup.h and setup.h_vms are not automatically
  45    updated so please update them manually (or modify the update-setup-h script
  46    to take care of them...).
  47
  48 c) update configure.in
  49
  50    Here you need to add DEFAULT_wxUSE_FOO define. It should be added in the
  51    block beginning after WX_ARG_CACHE_INIT line and should default to "no" for
  52    "if DEBUG_CONFIGURE = 1" branch (this is used for absolutely minimal builds)
  53    and the same as default value in setup_inc.h in the "else" branch.
  54
  55    You also need to add a WX_ARG_ENABLE (or, if new functionality can be
  56    reasonably described as support for a 3rd party library, WX_ARG_WITH)
  57    line togetherw with all the existing WX_ARG_ENABLEs.
  58
  59    If you have a sample/foo which should be only built when wxUSE_FOO==1,
  60    then only add it to the SAMPLES_SUBDIRS if wxUSE_FOO=yes in configure.
  61
  62
  63 3. Documentation
  64 ----------------
  65
  66 Currently wxUSE_XXXs are documented in docs/latex/wx/wxusedef.tex and a few
  67 important global ones are in docs/latex/wx/cppconst.tex.
  68
  69
  70 === EOF ===
  71
  72 Author:  VZ
  73 Version: $Id$
  74