From a65e5f4c1d77f250f7273d3534259cb3b0ec5f4d Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Mon, 29 Nov 2021 13:50:44 +0100 Subject: [PATCH] Explain better how to add data files to a sample Also don't duplicate this information in both how-to-add-new-sample.md and how-to-add-files-to-build-system.md, just reference the former in the latter instead. Also fix some Markdown markup. --- .../how-to-add-files-to-build-system.md | 21 +++---------- docs/contributing/how-to-add-new-sample.md | 30 ++++++++++++------- 2 files changed, 23 insertions(+), 28 deletions(-) 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 dc5ff3f7fb..e5f716d93e 100644 --- a/docs/contributing/how-to-add-files-to-build-system.md +++ b/docs/contributing/how-to-add-files-to-build-system.md @@ -120,24 +120,11 @@ wxUniversal, e.g. GDI classes. Files shared by all X Window System ports should be put into `XWIN_LOWLEVEL_SRC`. -Adding sample -------------- +Adding a new 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. - -The Windows resource specification should use the central .rc file: - - ../sample.rc - -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. - -Currently we commit all the generated makefiles. +This is explained in details in `how-to-add-new-sample.md` file, please see +there. Adding new core library diff --git a/docs/contributing/how-to-add-new-sample.md b/docs/contributing/how-to-add-new-sample.md index 4b0388d3ff..fe67c3a918 100644 --- a/docs/contributing/how-to-add-new-sample.md +++ b/docs/contributing/how-to-add-new-sample.md @@ -11,32 +11,38 @@ samples/ with demos/ where needed). Note that unless your sample requires something special you shouldn't add foo.rc, foo.ico, ... any more, please just reuse the generic `sample.*` - files in the samples subdirectory. + files in the samples subdirectory. In particular, the Windows resource + specification should use the central `.rc` file, i.e. do not use + `` bakefile tag unless it is really necessary. 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 + - create `foo.bkl`, typically by just copying an existing bakefile from + another sample (`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) + - add `` element with the data files used by the sample that need + to be copied to its build directory, if any (see e.g. + `samples/image/image.bkl` for an example of using this tag). - generate the makefiles for your sample using bakefile. For this you 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 + - install bakefile (see `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 You may also use `bakefile_gen -b ../../samples/foo/foo.bkl` to regenerate only the makefiles for this sample (path must be relative!) 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. + Again, see `how-to-add-files-to-build-system.md` for more information. 4. Modify configure.in Unix compilation: - if the sample should only be built if `wxUSE_FOO` is enabled, locate the test for `wxUSE_FOO = yes` in configure.in and add a line `SAMPLES_SUBDIRS="$SAMPLES_SUBDIRS foo"` under it - b) if it should be always built, locate the line `if test $wxUSE_GUI = yes` - near the end of configure.in and modify the assignment to - `SAMPLES_SUBDIRS` to include "foo" (put in alphabetical order) + - if it should be always built, locate the line `if test $wxUSE_GUI = yes` + near the end of configure.in and modify the assignment to + `SAMPLES_SUBDIRS` to include "foo" (put in alphabetical order) After this, regenerate configure from configure.in by running "autoconf" on a Unix system in the corresponding directory. @@ -44,17 +50,19 @@ samples/ with demos/ where needed). 5. Modify `build/cmake/samples/CMakeLists.txt` to include the sample in CMake. Add a new line like this: - wx_add_sample(foo DEPENDS wxUSE_FOO) + wx_add_sample(foo DEPENDS wxUSE_FOO) + + Use `DATA` CMake variable if the sample uses any data files. For a complete list of parameters to the `wx_add_sample()` function see the description in `build/cmake/functions.cmake`. 6. Add a short description of what the sample does and how does it work to the "samples overview" section in the wxWidgets manual. That section - lives in docs/doxygen/mainpages/samples.h; look at the descriptions for + 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 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. + and run the `./update-manifests.sh` script in distrib/scripts.