docs/tech/tn0001.txt

   1                     How to add a new sample to wxWidgets.
   2                     =====================================
   3
   4 To add a new sample "foo" under directory "samples/foo" you need to do
   5 the following: (note that all this applies also to demos: just replace
   6 samples/ with demos/ where needed).
   7
   8 1. Create the directory samples/foo locally and "svn add" it.
   9
  10 2. "svn add" the sample sources (usually based on minimal.cpp) as well.
  11
  12    Note that unless your sample requires something special you shouldn't
  13    add foo.rc, foo.ico, ... any more, please just reuse the generic sample.*
  14    files in the samples subdirectory.
  15
  16 3. Create the makefiles:
  17    a) modify samples/samples.bkl (just copy an existing line)
  18    b) create foo.bkl (sed 's/minimal/foo/g' minimal.bkl > foo.bkl is usually
  19       enough, but you may need to add more <wx-lib> lines if your sample uses
  20       anything not in the core lib)
  21    c) generate the makefiles for your sample using bakefile. For this you
  22       need to:
  23       (i) install bakefile (see http://bakefile.sf.net/)
  24       (ii) run bakefile_gen in build/bakefiles which will regenerate all
  25            makefiles which are not up to date
  26
  27       You may also use "bakefile_gen -b ../../samples/foo/foo.bkl" to
  28       regenerate only the makefiles for this sample (path must be relative!)
  29       or even add a "-f<compiler>" to generate just the makefiles for the given
  30       compiler (run 'bakefile --help' to get the list of possible values).
  31       See Technote #16 for more information.
  32    d) currently samples/samples.dsw needs to be updated manually as it's not
  33       generated by bakefile.
  34
  35 4. Modify configure.in Unix compilation:
  36    a) if the sample should only be built if "wxUSE_FOO" is enabled, locate
  37       the test for "wxUSE_FOO = yes" in configure.in and add a line
  38       SAMPLES_SUBDIRS="$SAMPLES_SUBDIRS foo" under it
  39    b) if it should be always built, locate the line "if test $wxUSE_GUI = yes"
  40       near the end of configure.in and modify the assignment to
  41       SAMPLES_SUBDIRS to include "foo" (put in alphabetical order)
  42
  43    After this, regenerate configure from configure.in
  44    by running "autoconf" on a Unix system in the corresponding directory.
  45
  46 5. Add a short description of what the sample does and how does it work
  47    to the "samples overview" section in the wxWidgets manual. That section
  48    lives in docs/doxygen/mainpages/samples.h; look at the descriptions for
  49    other samples, if you are not familiar with Doxygen.
  50
  51 6. Add any non-standard sample's files to build/bakefiles/make_dist.mk (the
  52    makefiles copies all bmp, cpp, h, ico, png, rc, xpm and makefiles by
  53    default, you only need to update it if the sample uses some other files)
  54    and run the ./update-manifests.sh script in distrib/scripts (don't forget
  55    to check the changes to manifests/*.rsp files in).
  56
  57 === EOF ===
  58
  59 Author:  VZ
  60 Version: $Id$