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

               How to add a new wxUSE_XXX preprocessor constant
               ================================================

0. Purpose
----------

Detailed description of what needs to be done when you want to add a new
wxUSE_XXX compilation flag. The text below assumes you need new wxUSE_FOO.


1. Overview
-----------

wxWidgets uses wxUSE_XXX macros for conditionally compiling in (or not)
optional components. In general, whenever a new non critical (i.e. not
absolutely required by important parts of the library) class Foo is added it
should use its own wxUSE_FOO compilation flag.

wxUSE_FOO must be always defined and have value of 0 or 1. Be careful with
testing for it in wx/foo.h: don't do it at the very beginning of the file
because then wxUSE_FOO would be not defined at all if the user directly
includes wx/foo.h, include "wx/defs.h" before testing for wxUSE_FOO.


2. Required files update
------------------------

Assuming wxUSE_FOO is used on all platforms, the following must be done:

a) update include/wx/setup_inc.h

   This file contains all common wxUSE_XXXs, and is used to update wxMSW, wxMac
   setup.h and Unix setup.h.in using build/update-setup-h. Please try to add
   the new define in a logical place (i.e. near any related ones) and write a
   detailed comment explaining what does it do and why would you want to turn
   it on/off. Choose the appropriate default value: this should be usually 1
   but can be 0 if there are some problems preventing the use of Foo by default
   (e.g. it requires installation of some non standard 3rd party libraries).
   After changing this file, run the update-setup-h script (this is probably
   better done on a Unix machine although it should work under Cygwin too).

b) update other setup.h files

   Currently include/wx/univ/setup.h and setup.h_vms are not automatically
   updated so please update them manually (or modify the update-setup-h script
   to take care of them...).

c) update configure.in

   Here you need to add DEFAULT_wxUSE_FOO define. It should be added in the
   block beginning after WX_ARG_CACHE_INIT line and should default to "no" for
   "if DEBUG_CONFIGURE = 1" branch (this is used for absolutely minimal builds)
   and the same as default value in setup_inc.h in the "else" branch.

   You also need to add a WX_ARG_ENABLE (or, if new functionality can be
   reasonably described as support for a 3rd party library, WX_ARG_WITH)
   line togetherw with all the existing WX_ARG_ENABLEs.

   If you have a sample/foo which should be only built when wxUSE_FOO==1,
   then only add it to the SAMPLES_SUBDIRS if wxUSE_FOO=yes in configure.


3. Documentation
----------------

Currently wxUSE_XXXs are documented in docs/latex/wx/wxusedef.tex and a few 
important global ones are in docs/latex/wx/cppconst.tex.


=== EOF ===

Author:  VZ
Version: $Id$
Commit	Line	Data
a3fc2e6c VZ	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)
a5f5f678	53	and the same as default value in setup_inc.h in the "else" branch.
a3fc2e6c VZ	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
fe906309 VZ	66	Currently wxUSE_XXXs are documented in docs/latex/wx/wxusedef.tex and a few
fe906309 VZ	67	important global ones are in docs/latex/wx/cppconst.tex.
a3fc2e6c VZ	68
	69
	70	=== EOF ===
	71
	72	Author: VZ
	73	Version: $Id$
	74