Rename tech notes to files with reasonable names.
Keep the old files to avoid breaking existing links to them, but just point to the files in the new contributing subdirectory with more meaningful names now. Also remove a couple of long obsolete tech notes. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@76689 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
parent
ff38c9ebdc
commit
4ce8a5ed00
122
docs/contributing/about-platform-toolkit-and-library-names.txt
Normal file
122
docs/contributing/about-platform-toolkit-and-library-names.txt
Normal file
@ -0,0 +1,122 @@
|
||||
wxWidgets naming conventions
|
||||
============================
|
||||
|
||||
Being a cross platform development library, it is naturally desirable
|
||||
(at least to me ;) for wxWidgets to be exploited in a fully cross
|
||||
platform development environment -- a single invocation of make should
|
||||
be sufficient to build target executables for a variety of host platforms
|
||||
when desired.
|
||||
|
||||
Since this is now in fact possible for at least the most commonly used
|
||||
platforms, wxWidgets has been structured to allow multiple, simultaneous
|
||||
installations of the library. Common files are shared, platform and port
|
||||
specific files and libraries are arranged so as to be unambiguous when
|
||||
installed together.
|
||||
|
||||
To manage this sanely we need a sufficiently descriptive and logical
|
||||
labelling convention for file and install path names -- this document (at
|
||||
least at its time of writing) describes the system we have adopted.
|
||||
|
||||
It is not fine grained enough to include every possible build configuration
|
||||
for wxWidgets, but is encompassing enough to maintain a relatively complete
|
||||
set of cross platform build tools on a single machine and to provide an
|
||||
obvious slot for new ports to slip into.
|
||||
|
||||
|
||||
For UNIX libraries, the canonical library name shall be of the form:
|
||||
|
||||
libwx_$(toolkit)$(widgetset)$(debug)-$(version)-$(host).$(lib_extension)
|
||||
|
||||
For MSW (native hosted only) libraries the library name should be of
|
||||
the form:
|
||||
|
||||
wx$(toolkit)$(widgetset)$(version)$(unicode)$(debug).$(lib_extension)
|
||||
|
||||
|
||||
Where:
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$toolkit must currently be one of the following:
|
||||
|
||||
msw
|
||||
gtk
|
||||
base
|
||||
mac
|
||||
motif
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$widgetset may be one of:
|
||||
|
||||
univ
|
||||
|
||||
or empty if the widget set is the same as the toolkit.
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$version is a string encoding the full version (major, minor, release)
|
||||
for MSW, or just the major and minor number for UNIX.
|
||||
|
||||
eg. for wxWidgets 2.3.2, $version = 232 for MSW or 2.3 for UNIX.
|
||||
|
||||
The rationale for this is that under UNIX-like systems it is desirable
|
||||
that differently 'minor numbered' releases can be installed together,
|
||||
meaning your old 2.2 apps can continue to work even if you migrate
|
||||
development to the next stable or unstable release (eg. 2.3, 2.4),
|
||||
but binary compatibility is maintained between point releases (those
|
||||
with the same major.minor number)
|
||||
|
||||
A known break in binary compatibility should be addressed by updating
|
||||
the library soname (see the notes in configure.in for details on this)
|
||||
|
||||
I do not know why MSW should not also omit the release number from
|
||||
$version. (maybe that will change by the time this document is ratified)
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$unicode and $debug are either empty or set to 'u' and 'd'
|
||||
respectively when enabled.
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$host is empty for a 'native' library, (that is one where the host
|
||||
system is the same as the build system) or set to the value returned
|
||||
by the autoconf ${host_alias} variable in configure for libraries
|
||||
that are cross compiled.
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$lib_extension is system specific and most usually set to .a for
|
||||
a static library, .dll for a MSW shared library, or .so.$so_version
|
||||
for a shared UNIX library.
|
||||
|
||||
====================================================================
|
||||
|
||||
|
||||
The installed location of the library specific setup.h is also
|
||||
determined by the values of these items. On UNIX systems they
|
||||
will be found in:
|
||||
|
||||
$(prefix)/lib/wx/include/$(toolkit)$(widgetset)$(debug)-$(version)-$(host)/wx/
|
||||
|
||||
which will be in the include search path returned by the relevant
|
||||
wx-config for that library. (or presumably set in the relevant
|
||||
make/project files for platforms that do not use wx-config)
|
||||
|
||||
====================================================================
|
||||
|
||||
|
||||
The port specific wx-config file for each library shall be named:
|
||||
|
||||
wx-$(toolkit)$(widgetset)$(debug)-$(version)-$(host)-config
|
||||
|
||||
${prefix}/bin/wx-config shall exist as a link to (or copy of) one of
|
||||
these port specific files (on platforms which support it) and as such
|
||||
it defines the default build configuration for wxApps on the system.
|
||||
It may be modified by the system user at any time.
|
||||
|
||||
|
||||
|
||||
---==O==---
|
||||
|
||||
51
docs/contributing/about-version-numbers.txt
Normal file
51
docs/contributing/about-version-numbers.txt
Normal file
@ -0,0 +1,51 @@
|
||||
All about wxWidgets Version Numbers
|
||||
===================================
|
||||
|
||||
1. Where to update the version numbers:
|
||||
|
||||
There are several places in the wxWidgets source tree that
|
||||
define the version number for the library.
|
||||
|
||||
The script misc/scripts/inc_release can be used for incrementing the release
|
||||
field of the version, i.e. changing 2.8.x to 2.8.x+1 but it does not take
|
||||
care of version.bkl and can't be used for changing the other version
|
||||
components, this needs to be done manually. It also doesn't update
|
||||
version.bkl file which always needs to be updated manually, follow the
|
||||
instructions there.
|
||||
|
||||
Here is the list of files that need to be updated:
|
||||
|
||||
build/bakefiles/version.bkl {C:R:A} [NOT UPDATED AUTOMATICALLY]
|
||||
build/bakefiles/wxpresets/presets/wx.bkl [NOT UPDATED AUTOMATICALLY]
|
||||
configure.in
|
||||
build/osx/wxvers.xcconfig
|
||||
docs/changes.txt
|
||||
docs/readme.txt (date needs manual editing) [NOT UPDATED AUTOMATICALLY]
|
||||
docs/doxygen/Doxyfile (PROJECT_NUMBER and DOCSET_FEEDNAME)
|
||||
docs/doxygen/latexdocstart.inc
|
||||
docs/doxygen/mainpages/manual.h (just date) [NOT UPDATED AUTOMATICALLY]
|
||||
docs/msw/install.txt {major release only}
|
||||
include/wx/version.h
|
||||
include/wx/osx/config_xcode.h
|
||||
samples/Info.plist
|
||||
samples/docview/Info.plist
|
||||
samples/minimal/Info_carbon.plist
|
||||
samples/minimal/Info_cocoa.plist
|
||||
samples/minimal/borland_ide.cpp {major release only}
|
||||
|
||||
Do not forget to rebake everything after updating version.bkl!
|
||||
|
||||
2. When to update the version numbers:
|
||||
|
||||
Version should be updated immediately after releasing the previous version
|
||||
so that the sources in the repository always correspond to the next release
|
||||
and not the past one.
|
||||
|
||||
See also tn0020.txt.
|
||||
|
||||
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
|
||||
287
docs/contributing/binary-compatibility.txt
Normal file
287
docs/contributing/binary-compatibility.txt
Normal file
@ -0,0 +1,287 @@
|
||||
Binary Compatibility and wxWidgets
|
||||
==================================
|
||||
0. Purpose
|
||||
----------
|
||||
|
||||
This is a broad technote covering all aspects of binary compatibility with
|
||||
wxWidgets.
|
||||
|
||||
1. Releases
|
||||
-----------
|
||||
|
||||
General overview of releases can be found in tn0012.txt, but for
|
||||
completeness the wxWidgets release version number is as follows:
|
||||
|
||||
2.6.2
|
||||
|
||||
Where
|
||||
|
||||
2 6 2
|
||||
Major Minor Release
|
||||
|
||||
(I.E. Major.Minor.Release).
|
||||
|
||||
All versions with EVEN minor version component (e.g. 2.4.x, 2.6.x etc.)
|
||||
are expected to be binary compatible (ODD minors are development versions
|
||||
and the compatibility constraints don't apply to them). Note that by
|
||||
preserving binary compatibility we mean BACKWARDS compatibility only,
|
||||
meaning that applications built with old wxWidgets headers should continue
|
||||
to work with new wxWidgets (shared/dynamic) libraries without the need to
|
||||
rebuild. There is no requirement to preserve compatibility in the other
|
||||
direction (i.e. make new headers compatible with old libraries) as this
|
||||
would preclude any additions whatsoever to the stable branch. But see
|
||||
also section (4).
|
||||
|
||||
|
||||
2. What kind of changes are NOT binary compatible
|
||||
-------------------------------------------------
|
||||
|
||||
If its still up, the KDE guide is a good reference:
|
||||
http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++
|
||||
|
||||
The changes that are NOT binary compatible:
|
||||
- Adding a virtual function
|
||||
- Changing the name of a any function or variable
|
||||
- Changing the signature of a virtual function (adding a parameter,
|
||||
even a default one)
|
||||
- Changing the order of the virtual functions in a class
|
||||
["switching" them, etc.]
|
||||
- Changing access privileges of a function: some compilers (among which MSVC)
|
||||
use the function access specifier in its mangled name. Moreover, while
|
||||
changing a private function to public should be compatible (as the old
|
||||
symbol can't be referenced from outside the library anyhow), changing a
|
||||
virtual private function to public is NOT compatible because the old symbol
|
||||
is referenced by the virtual tables in the executable code and so an old
|
||||
program compiled with MSVC wouldn't start up with a new DLL even if it
|
||||
doesn't use the affected symbol at all!
|
||||
- Adding a member variable
|
||||
- Changing the order of non-static member variables
|
||||
|
||||
|
||||
3. Changes which are compatible
|
||||
-------------------------------
|
||||
|
||||
- Adding a new class
|
||||
- Adding a new non-virtual method to an existing class
|
||||
- Adding a new constructor to an existing class
|
||||
- Overriding the implementation of an existing virtual function
|
||||
[this is considered to be backwards binary compatible until we find a
|
||||
counter example; currently it's known to work with Apple gcc at least]
|
||||
- Anything which doesn't result in ABI change at all, e.g. adding new
|
||||
macros, constants and, of course, private changes in the implementation
|
||||
|
||||
|
||||
4. wxABI_VERSION and "forward" binary compatibility
|
||||
--------------------------------------------------
|
||||
|
||||
As mentioned we do not support "forward" binary compatibility, that is the
|
||||
ability to run applications compiled with new wxWidgets headers on systems
|
||||
with old wxWidgets libraries.
|
||||
|
||||
However, for the developers who want to ensure that their application works
|
||||
with some fixed old wxWidgets version and doesn't (inadvertently) require
|
||||
features added in later releases, we provide the macro wxABI_VERSION which
|
||||
can be defined to restrict the API exported by wxWidgets headers to that of
|
||||
a fixed old release.
|
||||
|
||||
For this to work, all new symbols added to binary compatible releases must
|
||||
be #if'ed with wxABI_VERSION.
|
||||
|
||||
The layout of wxABI_VERSION is as follows:
|
||||
|
||||
20602
|
||||
|
||||
where
|
||||
|
||||
2 06 02
|
||||
Major Minor Release
|
||||
|
||||
I.E. it corresponds to the wxWidgets release in (1).
|
||||
|
||||
An example of using wxABI_VERSION is as follows for symbols
|
||||
only in a 2.6.2 release:
|
||||
|
||||
#if wxABI_VERSION >= 20602 /* 2.6.2+ only */
|
||||
bool Load(const wxURI& location, const wxURI& proxy);
|
||||
|
||||
wxFileOffset GetDownloadProgress();
|
||||
wxFileOffset GetDownloadTotal();
|
||||
|
||||
bool ShowPlayerControls(
|
||||
wxMediaCtrlPlayerControls flags =
|
||||
wxMEDIACTRLPLAYERCONTROLS_DEFAULT);
|
||||
|
||||
//helpers for the wxPython people
|
||||
bool LoadURI(const wxString& fileName)
|
||||
{ return Load(wxURI(fileName)); }
|
||||
bool LoadURIWithProxy(const wxString& fileName, const wxString& proxy)
|
||||
{ return Load(wxURI(fileName), wxURI(proxy)); }
|
||||
#endif
|
||||
|
||||
|
||||
5. Workarounds for adding virtual functions
|
||||
-------------------------------------------
|
||||
|
||||
Originally the idea for adding virtual functions to binary compatible
|
||||
releases was to pad out some empty "reserved" functions and then
|
||||
rename those later when someone needed to add a virtual function.
|
||||
|
||||
However, after there was some actual testing of the idea a lot of
|
||||
controversy erupted. Eventually we decided against the idea, and
|
||||
instead devised a new method for doing so called wxShadowObject.
|
||||
|
||||
wxShadowObject is a class derived from wxObject that provides a means
|
||||
of adding functions and/or member variables to a class internally
|
||||
to wxWidgets. It does so by storing these in a hash map inside of
|
||||
it, looking it up when the function etc. is called. wxShadowObject
|
||||
is generally stored inside a reserved member variable.
|
||||
|
||||
wxShadowObject resides in include/wx/clntdata.h.
|
||||
|
||||
To use wxShadowObject, you first call AddMethod or AddField with
|
||||
the first parameter being the name of the field and/or method
|
||||
you want, and the second parameter being the value of the
|
||||
field and/or method.
|
||||
|
||||
In the case of fields this is a void*, and in the case of method
|
||||
is a wxShadowObjectMethod which is a typedef:
|
||||
typedef int (*wxShadowObjectMethod)(void*, void*);
|
||||
|
||||
After you add a field, you can set it via SetField with the same
|
||||
parameters as AddField, the second parameter being the value to set
|
||||
the field to. You can get the field after you call AddField
|
||||
via GetField, with the parameters as the other two field functions,
|
||||
only in the case the second parameter is the fallback
|
||||
value for the field in the case of it not being found in the
|
||||
hash map.
|
||||
|
||||
You can call a method after you add it via InvokeMethod, which
|
||||
returns a bool indicating whether or not the method was found
|
||||
in the hash map, and has 4 parameters. The first parameter is
|
||||
the name of the method you wish to call, the second is the first
|
||||
parameter passed to the wxShadowObjectMethod, the third is the
|
||||
second parameter passed to that wxShadowObjectMethod, and the
|
||||
fourth is the return value of the wxShadowObjectMethod.
|
||||
|
||||
6. version-script.in
|
||||
--------------------
|
||||
|
||||
For ld/libtool we use sun-style version scripts. Basically
|
||||
anything which fits the conditions of being #if'ed via wxABI_VERSION
|
||||
needs to go here also.
|
||||
|
||||
See 'info ld scripts version' on a GNU system, it's online here:
|
||||
http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html
|
||||
|
||||
Or see chapter 5 of the 'Linker and Libraries Guide' for Solaris, available
|
||||
online here:
|
||||
http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWdev/LLM/p1.html
|
||||
|
||||
The file has the layout as follows:
|
||||
|
||||
@WX_VERSION_TAG@.X
|
||||
|
||||
Where X is the current Release as mentioned earlier, i.e. 2. This
|
||||
is following by an opening bracket "{", followed by "global:",
|
||||
followed by patterns matching added symbols, then followed by "}", and then
|
||||
the file is either followed by earlier Releases or ended by
|
||||
a @WX_VERSION_TAG@ block without the period or Release.
|
||||
|
||||
The patterns used to specify added symbols are globbing patters and can
|
||||
contain wildcards such as '*'.
|
||||
|
||||
For example for a new class member such as:
|
||||
wxFont wxGenericListCtrl::GetItemFont( long item ) const;
|
||||
|
||||
the mangled symbol might be:
|
||||
_ZNK17wxGenericListCtrl11GetItemFontEl
|
||||
|
||||
so a line like this could be added to version-script.in:
|
||||
*wxGenericListCtrl*GetItemFont*;
|
||||
|
||||
Allow for the fact that the name mangling is going to vary from compiler to
|
||||
complier.
|
||||
|
||||
When adding a class you can match all the symbols it adds with a single
|
||||
pattern, so long as that pattern is not likely to also match other symbols.
|
||||
For example for wxLogBuffer a line like this:
|
||||
*wxLogBuffer*;
|
||||
|
||||
|
||||
7. Checking the version information in libraries and programs
|
||||
-------------------------------------------------------------
|
||||
|
||||
On Sun there is a tool for this, see pvs(1). On GNU you can use objdump, below
|
||||
are some examples.
|
||||
|
||||
To see what versions of each library a program (or library) depends on:
|
||||
|
||||
$ objdump -p widgets | sed -ne '/Version References/,/^$/p'
|
||||
Version References:
|
||||
required from libgcc_s.so.1:
|
||||
0x0b792650 0x00 10 GCC_3.0
|
||||
required from libwx_based-2.6.so.0:
|
||||
0x0cca2546 0x00 07 WXD_2.6
|
||||
required from libstdc++.so.6:
|
||||
0x056bafd3 0x00 09 CXXABI_1.3
|
||||
0x08922974 0x00 06 GLIBCXX_3.4
|
||||
required from libwx_gtk2d_core-2.6.so.0:
|
||||
0x0a2545d2 0x00 08 WXD_2.6.2
|
||||
0x0cca2546 0x00 05 WXD_2.6
|
||||
required from libc.so.6:
|
||||
0x09691a75 0x00 04 GLIBC_2.2.5
|
||||
|
||||
To see what WXD_2.6.2 symbols a program uses:
|
||||
|
||||
$ objdump -T widgets | grep 'WXD_2\.6\.2'
|
||||
0000000000000000 g DO *ABS* 0000000000000000 WXD_2.6.2 WXD_2.6.2
|
||||
00000000004126d8 DF *UND* 0000000000000177 WXD_2.6.2 _ZN19wxTopLevelWindowGTK20RequestUserAttentionEi
|
||||
|
||||
To see what WXD_2.6.2 symbols a library defines:
|
||||
|
||||
$ objdump -T libwx_based-2.6.so | grep 'WXD_2\.6\.2' | grep -v 'UND\|ABS'
|
||||
0000000000259a10 w DO .data 0000000000000018 WXD_2.6.2 _ZTI19wxMessageOutputBest
|
||||
00000000002599e0 w DO .data 0000000000000028 WXD_2.6.2 _ZTV19wxMessageOutputBest
|
||||
000000000010a98e w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD0Ev
|
||||
0000000000114efb w DO .rodata 000000000000000e WXD_2.6.2 _ZTS11wxLogBuffer
|
||||
0000000000255590 w DO .data 0000000000000018 WXD_2.6.2 _ZTI11wxLogBuffer
|
||||
000000000011b550 w DO .rodata 0000000000000016 WXD_2.6.2 _ZTS19wxMessageOutputBest
|
||||
00000000000bfcc8 g DF .text 00000000000000dd WXD_2.6.2 _ZN11wxLogBuffer5DoLogEmPKcl
|
||||
000000000010a3a6 g DF .text 0000000000000153 WXD_2.6.2 _ZN19wxMessageOutputBest6PrintfEPKcz
|
||||
00000000000c0b22 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD0Ev
|
||||
00000000000bfc3e g DF .text 0000000000000089 WXD_2.6.2 _ZN11wxLogBuffer5FlushEv
|
||||
00000000000c0ad6 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD1Ev
|
||||
00000000000b1130 w DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBufferC1Ev
|
||||
00000000000c095c w DF .text 0000000000000029 WXD_2.6.2 _ZN19wxMessageOutputBestC1Ev
|
||||
00000000000c08e8 w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD1Ev
|
||||
00000000002554c0 w DO .data 0000000000000038 WXD_2.6.2 _ZTV11wxLogBuffer
|
||||
00000000000bfda6 g DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBuffer11DoLogStringEPKcl
|
||||
00000000000abe10 g DF .text 0000000000000088 WXD_2.6.2 _ZN14wxZipFSHandler7CleanupEv
|
||||
|
||||
|
||||
8. Testing binary compatibility between releases
|
||||
------------------------------------------------
|
||||
|
||||
An easy way of testing binary compatibility is just to build wxWidgets
|
||||
in dll/dynamic library mode and then switch out the current library
|
||||
in question with an earlier stable version of the library, then running
|
||||
the application in question again. If it runs OK then there is usually
|
||||
binary compatibility between those releases.
|
||||
|
||||
You can also break into your debugger or whatever program you want
|
||||
to use and check the memory layout of the class. If it is the same
|
||||
then it is binary compatible.
|
||||
(In GDB the command x/d will show addresses as pointers to functions if
|
||||
possible so you can see if the order of the functions in vtbl doesn't change.)
|
||||
|
||||
Another way to check for binary compatibility is to build wxWidgets in shared mode
|
||||
and use the 'abicheck.sh --generate' script before doing your changes to generate
|
||||
the current ABI (if the 'expected_abi' file is not already in the repo).
|
||||
Then rebuild wxWidgets with your changes and use 'abicheck.sh' to compare the
|
||||
resulting ABI with the expected one.
|
||||
Note that the abicheck.sh script is in the "lib" folder.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: RN
|
||||
315
docs/contributing/how-to-add-class-documentation.txt
Normal file
315
docs/contributing/how-to-add-class-documentation.txt
Normal file
@ -0,0 +1,315 @@
|
||||
Adding wxWidgets class documentation
|
||||
====================================
|
||||
|
||||
This note is aimed at people wishing to add documentation for a
|
||||
class to either the main wxWidgets manual, or to their own
|
||||
manual.
|
||||
|
||||
wxWidgets uses Doxygen to process header input files with embedded
|
||||
documentation in the form of C++ comments and output in HTML, and XML
|
||||
(Doxygen itself can also output Latex, manpages, RTF, PDF etc).
|
||||
See http://www.doxygen.org for more info about Doxygen.
|
||||
|
||||
If you want to add documentation of a new class/function to the
|
||||
existing manual in docs/doxygen, you need to create a new .h file,
|
||||
e.g. myclass.h, under the interface folder, which contains the public
|
||||
interface of the new class/function in C++ syntax.
|
||||
The documentation can then be added in form of Doxygen comments to
|
||||
the header file.
|
||||
|
||||
You may also want to write a separate topic file,
|
||||
e.g. docs/doxygen/overviews/myclass.h, and add the entry to
|
||||
docs/doxygen/mainpages/topics.h.
|
||||
|
||||
If applicable, also add an entry to one of the docs/doxygen/mainpages/cat_*.h
|
||||
files.
|
||||
|
||||
You can generate a first raw version of myclass.h simply taking its
|
||||
"real" header and removing all the private and protected sections and
|
||||
in general removing everything the user "shouldn't know": i.e. all things
|
||||
which are implementation details.
|
||||
|
||||
|
||||
Running Doxygen
|
||||
===============
|
||||
|
||||
First, make sure you have a recent version of Doxygen installed in your system
|
||||
(you'll need Doxygen >= 1.5.7).
|
||||
|
||||
On Unix:
|
||||
|
||||
1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate]
|
||||
|
||||
On Windows:
|
||||
1) cd wxWidgets/docs/doxygen
|
||||
2) run regen.bat [format-to-generate]
|
||||
|
||||
If you don't specify which format to [re]generate, all output formats will
|
||||
be enabled. Possible values for [format-to-generate] are: "html", "chm", "latex",
|
||||
"xml" and "all".
|
||||
|
||||
The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder.
|
||||
|
||||
|
||||
Important Dos and Don'ts
|
||||
========================
|
||||
|
||||
DO:
|
||||
|
||||
- Doxygen supports both commands in the form \command and @command;
|
||||
all wxWidgets documentation uses the @command form.
|
||||
Follow strictly this rule.
|
||||
|
||||
- strive to use dedicated Doxygen commands for e.g. notes, lists,
|
||||
sections, etc. The "Special commands" page:
|
||||
http://www.stack.nl/~dimitri/doxygen/commands.html
|
||||
is your friend!
|
||||
It's also very important to make a consistent use of the ALIASES
|
||||
defined by wxWidgets' Doxyfile. Open that file for more info.
|
||||
|
||||
- when you write true, false and NULL with their C++ semantic meaning,
|
||||
then use the @true, @false and @NULL commands.
|
||||
|
||||
- separate different paragraphs with an empty comment line.
|
||||
This is important otherwise Doxygen puts everything in the same
|
||||
paragraph making the result less readable.
|
||||
|
||||
- leave a blank comment line between a @section, @subsection, @page
|
||||
and the next paragraph.
|
||||
|
||||
- test your changes, both reading the generated HTML docs and by looking
|
||||
at the "doxygen.log" file produced (which will warn you about any
|
||||
eventual mistake found in the comments).
|
||||
|
||||
- quote all the following characters prefixing them with a "@" char:
|
||||
|
||||
@ $ \ & < > # %
|
||||
|
||||
unless they appear inside a @code or @verbatim section
|
||||
(you can also use HTML-style escaping, e.g. & rather than @ escaping)
|
||||
|
||||
- when using a Doxygen alias like @itemdef{}, you need to escape the
|
||||
comma characters which appear on the first argument, otherwise Doxygen
|
||||
will interpret them as the marker of the end of the first argument and
|
||||
the beginning of the second argument's text.
|
||||
|
||||
E.g. if you want to define the item "wxEVT_MACRO(id, func)" you need to
|
||||
write:
|
||||
@itemdef{wxEVT_MACRO(id\, func), This is the description of the macro}
|
||||
|
||||
Also note that you need to escape only the commas of the first argument's
|
||||
text; second argument can have up to 10 commas unescaped (see the Doxyfile
|
||||
for the trick used to implement this).
|
||||
|
||||
- for linking use one of:
|
||||
=> the @ref command to refer to topic overviews;
|
||||
=> the () suffix to refer to function members of the same class you're
|
||||
documenting or to refer to global functions or macros;
|
||||
=> the classname:: operator to refer to functions of classes different
|
||||
from the one you're documenting;
|
||||
=> the :: prefix to refer to global variables (e.g. ::wxEmptyString).
|
||||
Class names are auto-linked by Doxygen without the need of any explicit
|
||||
command.
|
||||
|
||||
DON'T:
|
||||
|
||||
- use jargon, such as 'gonna', or omit the definite article.
|
||||
The manual is intended to be a fluent, English document and
|
||||
not a collection of rough notes.
|
||||
|
||||
- use non-alphanumeric characters in link anchors.
|
||||
|
||||
- use Doxygen @b @c @e commands when referring to more than a single word;
|
||||
in that case you need to use the <b>...</b>, <tt>...</tt>, <em>...</em>
|
||||
HTML-style tags instead
|
||||
|
||||
- use HTML style tags for creation of tables or lists.
|
||||
Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and
|
||||
@beginDefList, @itemdef, @endDefList, etc.
|
||||
See the Doxyfile.inc for more info.
|
||||
|
||||
|
||||
Documentation comment for a class
|
||||
=================================
|
||||
|
||||
Start off with:
|
||||
|
||||
/**
|
||||
@class wxMyClass
|
||||
|
||||
...here goes the description...
|
||||
|
||||
@beginEventTable
|
||||
@event{EVT_SOME_EVENT(id, func)}:
|
||||
Description for EVT_SOME_EVENT.
|
||||
@endEventTable
|
||||
|
||||
@beginStyleTable
|
||||
@style{wxSOME_STYLE}:
|
||||
Description for wxSOME_STYLE.
|
||||
...
|
||||
@endStyleTable
|
||||
|
||||
@beginExtraStyleTable
|
||||
@style{wxSOME_EXTRA_STYLE}:
|
||||
Description for wxSOME_EXTRA_STYLE.
|
||||
...
|
||||
@endExtraStyleTable
|
||||
|
||||
@library{wxbase}
|
||||
@category{cat_shortcut}
|
||||
|
||||
@nativeimpl{wxgtk, wxmsw, ...}
|
||||
@onlyfor{wxgtk, wxmsw, ...}
|
||||
|
||||
@appearance{button.png}
|
||||
|
||||
@stdobjects
|
||||
...here goes the list of predefined instances...
|
||||
|
||||
@see ...here goes the see-also list...
|
||||
you can make references to topic overviews or other
|
||||
manual pages using the @ref command
|
||||
*/
|
||||
|
||||
Note that everything *except* the @class, @library and @category
|
||||
commands are optionals.
|
||||
|
||||
Also note that if you use @section and @subsection in the class description
|
||||
(at the beginning), you should use as the section's anchor name "xxxx_yyyy"
|
||||
where "xxxx" is the class name without the initial "wx" in lowercase
|
||||
and "yyyy" is a lowercase word which uniquely identifies that section.
|
||||
E.g.:
|
||||
|
||||
/**
|
||||
@class wxMyClass
|
||||
|
||||
This class does not exist really and is only used as an example
|
||||
of best documentation practices.
|
||||
|
||||
@section myclass_special Special functions of this class
|
||||
|
||||
This section describes the functions whose usage is reserved for
|
||||
wxWidgets internal mechanisms... etc etc...
|
||||
|
||||
|
||||
@section myclass_custom Customizing wxMyClass
|
||||
|
||||
What if you want to customize this powerful class?
|
||||
First you should do this and that, etc etc...
|
||||
|
||||
|
||||
@library{wxbase}
|
||||
@category{misc}
|
||||
|
||||
@see wxMyOtherClass
|
||||
*/
|
||||
|
||||
|
||||
|
||||
Documentation comment for a function
|
||||
====================================
|
||||
|
||||
Start off with:
|
||||
|
||||
/**
|
||||
...here goes the description of the function....
|
||||
|
||||
@param param1
|
||||
...here goes the description for the first parameter of this function
|
||||
@param param2
|
||||
...here goes the description for the second parameter of this function
|
||||
...
|
||||
|
||||
@return
|
||||
...here goes the description of what the function returns...
|
||||
|
||||
@note ...here go any eventual notes about this function...
|
||||
|
||||
@remarks ...here go any eventual remarks about this function...
|
||||
|
||||
@see ...here goes the see-also list...
|
||||
*/
|
||||
|
||||
Note that the @return, @note, @remarks, @see commands are optional.
|
||||
|
||||
The @param command has an optional attribute specifying the direction of
|
||||
the attribute. Possible values are "in" and "out". E.g.
|
||||
|
||||
/**
|
||||
* Copies bytes from a source memory area to a destination memory area,
|
||||
* where both areas may not overlap.
|
||||
* @param[out] dest The memory area to copy to.
|
||||
* @param[in] src The memory area to copy from.
|
||||
* @param[in] n The number of bytes to copy.
|
||||
* @param[in,out] pmisc Used both as input and as output.
|
||||
*/
|
||||
void func(void *dest, const void *src, size_t n, void *pmisc);
|
||||
|
||||
|
||||
Documentation comment for a topic overview
|
||||
==========================================
|
||||
|
||||
Topic overviews are stored inside the docs/doxygen/overviews folder
|
||||
and are completely placed inside a single comment block in the form of:
|
||||
|
||||
/*!
|
||||
|
||||
@page overview_tname wxSomeStuff overview
|
||||
|
||||
This page provides an overview of the wxSomeStuff and related classes.
|
||||
....
|
||||
|
||||
@li @ref overview_tname_intro
|
||||
@li @ref overview_tname_details
|
||||
...
|
||||
|
||||
<hr>
|
||||
|
||||
|
||||
@section overview_tname_intro Introduction
|
||||
|
||||
...here goes the introduction to this topic...
|
||||
|
||||
|
||||
@section overview_tname_details Details
|
||||
|
||||
...here go the details to this topic...
|
||||
|
||||
*/
|
||||
|
||||
Note that there is a convention in the anchor link names.
|
||||
Doxygen in fact requires that for each @page, @section, @subsection, etc tag,
|
||||
there is a corresponding link anchor.
|
||||
|
||||
The following conventions are used in wxWidgets doxygen comments:
|
||||
|
||||
1) all "main" pages of the manual (those which are placed in
|
||||
docs/doxygen/mainpages) have link anchors which begin with "page_"
|
||||
|
||||
2) all topic overviews (those which are placed in docs/doxygen/overviews) have
|
||||
link anchors which begin with "overview_"
|
||||
|
||||
3) all @section, @subsection, @subsubsection tags should have as link anchor
|
||||
name the name of the parent section plus a specific word separated with an
|
||||
underscore; e.g.:
|
||||
|
||||
/*!
|
||||
|
||||
@page overview_tname wxSomeStuff overview
|
||||
|
||||
@section overview_tname_intro Introduction
|
||||
@subsection overview_tname_intro_firstpart First part
|
||||
@subsection overview_tname_intro_secondpart Second part
|
||||
@subsubsection overview_tname_intro_secondpart_sub Second part subsection
|
||||
@subsection overview_tname_intro_thirdpart Third part
|
||||
|
||||
@section overview_tname_details Details
|
||||
...
|
||||
|
||||
*/
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: FM (along the lines of the previous technote about tex2rtf)
|
||||
227
docs/contributing/how-to-add-files-to-build-system.txt
Normal file
227
docs/contributing/how-to-add-files-to-build-system.txt
Normal file
@ -0,0 +1,227 @@
|
||||
How to add new files and libraries to wxWidgets build system
|
||||
============================================================
|
||||
|
||||
|
||||
1. 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.2 installed on Unix and either use Bakefile installer or have
|
||||
Python on Windows.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
You can use Bakefile to generate makefiles or projects customized to your
|
||||
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:
|
||||
bakefile -v -fmsvc6prj -o../wxmy.dsw -DRUNTIME_LIBS=dynamic
|
||||
-DDEBUG_INFO=default -DDEBUG_FLAG=default
|
||||
-DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1
|
||||
-DMONOLITHIC=0 -DUSE_GUI=1 -DWXUNIV=0 wx.bkl
|
||||
Or monolithic instead of multilib (the default):
|
||||
bakefile -v -fmsvc6prj -o../wxmono.dsw -DRUNTIME_LIBS=dynamic
|
||||
-DDEBUG_INFO=default -DDEBUG_FLAG=default
|
||||
-DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1
|
||||
-DMONOLITHIC=1 -DUSE_GUI=1 wx.bkl
|
||||
Or monolithic wxBase:
|
||||
bakefile -v -fmsvc6prj -o../wxBase.dsw -DRUNTIME_LIBS=dynamic
|
||||
-DDEBUG_INFO=default -DDEBUG_FLAG=default
|
||||
-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 <add-flags> and <del-flags> directives
|
||||
and use bakefile_gen instead of running bakefile directly.
|
||||
|
||||
|
||||
2. Bakefile files organization
|
||||
------------------------------
|
||||
|
||||
Makefile are generated from .bkl files ("bakefiles") from two places:
|
||||
- $(wx)/build/bakefiles directory
|
||||
- samples directories
|
||||
$(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
|
||||
|
||||
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
|
||||
|
||||
|
||||
3. 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.
|
||||
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
sources on all platforms (e.g. wxXml or wxXML) -- simply add the file to e.g.
|
||||
HTML_SRC or HTML_HDR.
|
||||
|
||||
If the file is used only on one platform and is part of wxBase, add it to
|
||||
BASE_{platform}_SRC/HDR. If it is used on all platforms, add it to BASE_CMN.
|
||||
If it is built on more than one platform but not on all of them, add the file
|
||||
to *all platforms that use it*!
|
||||
|
||||
If a file is not wxBase file, but GUI file, then the variables are named after
|
||||
toolkits/ports, not platforms. Same rules as for wxBase files apply
|
||||
(substitute "platform" with "toolkit"). Make sure you correctly choose between
|
||||
{port}_LOWLEVEL_SRC and {port}_SRC -- the former is for files used by
|
||||
wxUniversal, e.g. GDI classes. Files shared by all X Window System ports
|
||||
should be put into XWIN_LOWLEVEL_SRC.
|
||||
|
||||
|
||||
4. 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 <wx-data> node
|
||||
in the sample's bakefile (see e.g. samples/image/image.bkl for an example).
|
||||
Make sure to add <wx-lib> statements for all libraries from multilib build
|
||||
that are required by the sample.
|
||||
|
||||
The Windows resource specification should use the central .rc file:
|
||||
|
||||
<win32-res>../sample.rc</win32-res>
|
||||
|
||||
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 the generated makefiles except .dms, .vcp.
|
||||
|
||||
|
||||
5. Adding new core library
|
||||
--------------------------
|
||||
|
||||
When adding new library to the core set of libraries, the files must be
|
||||
added to both a newly added library in multilib build and into the single
|
||||
library built in monolithic mode. We will assume that the new library is
|
||||
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.
|
||||
* 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.
|
||||
* 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).
|
||||
* 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.
|
||||
|
||||
(You can apply different approaches to HDR and SRC variables, if e.g.
|
||||
headers are all common but sources are not.)
|
||||
|
||||
Note that the conditions can only test for equality, due to limitations of
|
||||
native make tools.
|
||||
|
||||
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.
|
||||
* 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:
|
||||
<set var="WXLIB_FOO">
|
||||
<if cond="MONOLITHIC=='0'">$(mk.evalExpr(wxwin.mkLibName('foo')))</if>
|
||||
</set>
|
||||
|
||||
c) Modify monolithic.bkl to add files to monolithic build: it's enough to add
|
||||
FOO_SRC to MONOLIB_GUI_SRC or MONOLIB_SRC, depending on whether wxFoo uses
|
||||
GUI or not.
|
||||
|
||||
d) Modify multilib.bkl to add files to multilib build: add foolib and foodll
|
||||
targets. Don't use wxBase targets as the template, use e.g. wxXML or wxHTML.
|
||||
Make sure WXMAKINGDLL_FOO is defined in foodll.
|
||||
|
||||
e) Regenerate all makefiles (don't forget to run autoconf)
|
||||
|
||||
f) Update configure.in and wx-config.in to contain information about
|
||||
the library and needed linker flags:
|
||||
* Add "foo" to BUILT_WX_LIBS in configure.in.
|
||||
* If appropriate, but it rarely is, so normally this should _not_ be done,
|
||||
add "foo" to either STD_BASE_LIBS or STD_GUI_LIBS in configure.in.
|
||||
* If wxFoo links against additional libraries, add necessary linker
|
||||
flags and libraries to ldflags_foo and ldlibs_foo variables in
|
||||
wx-config.in (both are optional).
|
||||
|
||||
g) Update dlimpexp.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add
|
||||
#define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in
|
||||
dlimpexp.h) and to define WXDLLIMPEXP_FOO and WXDLLIMPEXP_DATA_FOO. You
|
||||
can copy e.g. WXDLLIMPEXP_NET definition, it is something like this:
|
||||
#ifdef WXMAKINGDLL_NET
|
||||
#define WXDLLIMPEXP_NET WXEXPORT
|
||||
#define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type
|
||||
#elif defined(WXUSINGDLL)
|
||||
#define WXDLLIMPEXP_NET WXIMPORT
|
||||
#define WXDLLIMPEXP_DATA_NET(type) WXIMPORT type
|
||||
#else // not making nor using DLL
|
||||
#define WXDLLIMPEXP_NET
|
||||
#define WXDLLIMPEXP_DATA_NET(type) type
|
||||
#endif
|
||||
Don't forget to add WXDLLIMPEXP_FWD_FOO definitions too.
|
||||
Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions.
|
||||
|
||||
h) Add this code to one of wxFoo's files (the more often used, the better):
|
||||
// DLL options compatibility check:
|
||||
#include "wx/app.h"
|
||||
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)
|
||||
to show the dependencies of the new library.
|
||||
|
||||
j) Also please add 4 #pragma comment(lib, "foo") (for Unicode/ANSI
|
||||
Release/Debug 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.
|
||||
|
||||
=== EOF ===
|
||||
|
||||
67
docs/contributing/how-to-add-new-font-encoding.txt
Normal file
67
docs/contributing/how-to-add-new-font-encoding.txt
Normal file
@ -0,0 +1,67 @@
|
||||
How to add a new font encoding to wxWidgets
|
||||
===========================================
|
||||
|
||||
I. Introduction
|
||||
---------------
|
||||
|
||||
wxWidgets has built in support for a certain number of font encodings (which
|
||||
is synonymous with code sets and character sets for us here even though it is
|
||||
not exactly the same thing), look at include/wx/fontenc.h for the full list.
|
||||
This list is far from being exhaustive though and if you have enough knowledge
|
||||
about an encoding to add support for it to wxWidgets, this tech note is for
|
||||
you!
|
||||
|
||||
A word of warning though: this is written out of my head and is surely
|
||||
incomplete. Please correct the text here, especially if you detect problems
|
||||
when you try following it.
|
||||
|
||||
Also note that I completely ignore all the difficult issues of support for
|
||||
non European languages in the GUI (i.e. BiDi and text orientation support).
|
||||
|
||||
|
||||
II. The receipt
|
||||
---------------
|
||||
|
||||
Suppose you want to add support for Klingon to wxWidgets. This is what you'd
|
||||
have to do:
|
||||
|
||||
1. include/wx/fontenc.h: add a new wxFONTENCODING_KLINGON enum element, if
|
||||
possible without changing the values of the existing elements of the enum
|
||||
and be careful to now make it equal to some other elements -- this means
|
||||
that you have to put it before wxFONTENCODING_MAX
|
||||
|
||||
2. wxFONTENCODING_MAX must be the same as the number of elements in 3
|
||||
(hopefully) self explanatory arrays in src/common/fmapbase.cpp:
|
||||
a) gs_encodings
|
||||
b) gs_encodingDescs
|
||||
c) gs_encodingNames
|
||||
|
||||
You must update all of them, e.g. you'd add wxFONTENCODING_KLINGON,
|
||||
"Klingon (Star Trek)" and "klingon" to them in this example. The latter
|
||||
name should ideally be understandable to both Win32 and iconv as it is used
|
||||
to convert to/from this encoding under Windows and Unix respectively.
|
||||
Typically any reasonable name will be supported by iconv, if unsure run
|
||||
"iconv -l" on your favourite Unix system. For the list of charsets
|
||||
supported under Win32, look under HKEY_CLASSES_ROOT\MIME\Database\Charset
|
||||
in regedit. Of course, being consistent with the existing encoding names
|
||||
wouldn't hurt neither.
|
||||
|
||||
3. Normally you don't have to do anything else if you've got support for this
|
||||
encoding under both Win32 and Unix. If you haven't, you should modify
|
||||
wxEncodingConverter to support it (this could be useful anyhow as a
|
||||
fallback for systems where iconv is unavailable). To do it you must:
|
||||
a) add a new table to src/common/unictabl.inc: note that this file is auto
|
||||
generated so you have to modify misc/unictabl script instead (probably)
|
||||
b) possibly update EquivalentEncodings table in src/common/encconv.cpp
|
||||
if wxFONTENCODING_KLINGON can be converted into another one
|
||||
(losslessly only or not?)
|
||||
|
||||
4. Add a unit test (see tn0017.txt) for support of your new encoding (with
|
||||
time we should have a wxCSConv unit test so you would just add a case to
|
||||
it for wxFONTENCODING_KLINGON) and test everything on as many different
|
||||
platforms as you can.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
59
docs/contributing/how-to-add-new-sample.txt
Normal file
59
docs/contributing/how-to-add-new-sample.txt
Normal file
@ -0,0 +1,59 @@
|
||||
How to add a new sample to wxWidgets.
|
||||
=====================================
|
||||
|
||||
To add a new sample "foo" under directory "samples/foo" you need to do
|
||||
the following: (note that all this applies also to demos: just replace
|
||||
samples/ with demos/ where needed).
|
||||
|
||||
1. Create the directory samples/foo locally and "svn add" it.
|
||||
|
||||
2. "svn 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.*
|
||||
files in the samples subdirectory.
|
||||
|
||||
3. Create the makefiles:
|
||||
a) modify samples/samples.bkl (just copy an existing line)
|
||||
b) create foo.bkl (sed 's/minimal/foo/g' minimal.bkl > foo.bkl is usually
|
||||
enough, but you may need to add more <wx-lib> lines if your sample uses
|
||||
anything not in the core lib)
|
||||
c) generate the makefiles for your sample using bakefile. For this you
|
||||
need to:
|
||||
(i) install bakefile (see http://bakefile.sf.net/)
|
||||
(ii) 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<compiler>" to generate just the makefiles for the given
|
||||
compiler (run 'bakefile --help' to get the list of possible values).
|
||||
See Technote #16 for more information.
|
||||
d) currently samples/samples.dsw needs to be updated manually as it's not
|
||||
generated by bakefile.
|
||||
|
||||
4. Modify configure.in Unix compilation:
|
||||
a) 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)
|
||||
|
||||
After this, regenerate configure from configure.in
|
||||
by running "autoconf" on a Unix system in the corresponding directory.
|
||||
|
||||
5. 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
|
||||
other samples, if you are not familiar with Doxygen.
|
||||
|
||||
6. 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).
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
120
docs/contributing/how-to-add-new-ui-bitmaps.txt
Normal file
120
docs/contributing/how-to-add-new-ui-bitmaps.txt
Normal file
@ -0,0 +1,120 @@
|
||||
How to add new bitmaps to wxWidgets UI elements
|
||||
===============================================
|
||||
|
||||
0. Introduction
|
||||
---------------
|
||||
|
||||
Since the introduction of wxArtProvider class, it is no longer desired to
|
||||
hardcode art resources (e.g. icons and toolbar or button bitmaps) into the
|
||||
code. This was previously done either by including the bitmap in win32
|
||||
resource file (include/wx/msw/wx.rc) or by including XPM files in the code.
|
||||
|
||||
wxArtProvider should be used instead, to allow users to customize the look of
|
||||
their wxWidgets app. This technote is a detailed description of steps needed
|
||||
when adding new bitmap/icon.
|
||||
|
||||
1. Adding new resource
|
||||
----------------------
|
||||
|
||||
(Please see wxArtProvider reference documentation for explanation of "art ID"
|
||||
and "art client" terms.)
|
||||
|
||||
First of all, you have to add new wxArtID constant to include/wx/artprov.h.
|
||||
Look for "Art IDs" and add new definition to the list, e.g.
|
||||
#define wxART_MY_BITMAP wxART_MAKE_ART_ID(wxART_MY_BITMAP)
|
||||
|
||||
Add it to interface/wx/artprov.h, too.
|
||||
|
||||
It may happen that the intended use of the new resource doesn't fit into any
|
||||
of defined client categories (search for "Art clients" in the header). In case
|
||||
the new resource is part of a larger category, you need to define a new
|
||||
client. Just add it to the list of existing clients (and don't forget to
|
||||
update artprov.tex):
|
||||
#define wxART_MY_CLIENT wxART_MAKE_CLIENT_ID(wxART_MY_CLIENT)
|
||||
|
||||
Alternatively, you may use wxART_OTHER when accessing the resource if the
|
||||
bitmap is standalone.
|
||||
|
||||
Once the header is updated, it's time to add XPM file with the bitmap to
|
||||
$(wx)/art. Add it to $(wx)/art if it is platform-independent or to
|
||||
$(wx)/art/$(toolkit) if it is something specific to one of the toolkits. Note
|
||||
that "specific to one of the toolkits" doesn't mean that the bitmap is *used*
|
||||
by only one toolkit, but that it doesn't make sense for any of the others! For
|
||||
example, a GTK wxART_WARNING icon ($(wx)/art/gtk/warning.xpm) is specific to
|
||||
wxGTK, but new_dir.xpm makes sense even under wxMSW even though it is
|
||||
currently only used by the generic file dialog. Remember that wxArtProvider
|
||||
can be used by users, not only the library.
|
||||
|
||||
Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated.
|
||||
This consists of two steps:
|
||||
|
||||
a) add #include line for your XPM file, e.g. #include "../../art/my_bmp.xpm"
|
||||
b) add ART(...) line to wxDefaultArtProvider::CreateBitmap(). The first
|
||||
argument is wxArtID, the other is XPM file name (w/o extension), e.g.
|
||||
ART(wxART_MY_BITMAP, my_bmp)
|
||||
|
||||
That's all. The bitmap is now available to wxArtProvider users.
|
||||
|
||||
Note: there's no difference between icons and bitmaps, always treat them as
|
||||
bitmaps inside wx(Default)ArtProvider.
|
||||
|
||||
1b. Adding Tango version of the resource.
|
||||
-----------------------------------------
|
||||
|
||||
While all the bitmaps are provided in XPM format so that they are available in
|
||||
all builds of wxWidgets, we also provide most of them in PNG format with full
|
||||
transparency support that is not available in XPM. Another advantage of the PNG
|
||||
versions is that the icons used are those of the Tango project and so have the
|
||||
consistent look, unlike the XPM ones.
|
||||
|
||||
So if you an icon exists in http://tango.freedesktop.org/Tango_Icon_Gallery you
|
||||
should add it too. For this you need to:
|
||||
|
||||
1. Convert the PNG to a C array of bytes suitable for inclusion in the code.
|
||||
This is done using misc/scripts/png2c.py script, e.g. if the variable "f"
|
||||
contains the name of the icon you want to add and you have installed Tango
|
||||
icons in a standard location under a Linux system:
|
||||
|
||||
./misc/scripts/png2c.py -s /usr/share/icons/Tango/{16x16,24x24}/*/$f.png >
|
||||
art/tango/${f//-/_}.h
|
||||
|
||||
Of course, the same command may be ran with different paths under Windows.
|
||||
Just remember to add both 16 and 24 pixel versions of the bitmap to the
|
||||
header and use the "-s" option to embed the image size in its array name.
|
||||
|
||||
2. Add #include for the newly created file to src/common/arttango.cpp.
|
||||
|
||||
3. Add an entry to s_allBitmaps array in the same file.
|
||||
|
||||
|
||||
2. Accessing the resource
|
||||
-------------------------
|
||||
|
||||
The file that will use the bitmap needs to include "wx/artprov.h". The code to
|
||||
access the bitmap (or icon) is trivial:
|
||||
|
||||
wxBitmap bmp = wxArtProvider::GetBitmap(wxART_MY_BITMAP, wxART_MY_CLIENT);
|
||||
// this would be "wxBitmap bmp(my_bmp_xpm);" before
|
||||
wxIcon icon = wxArtProvider::GetIcon(wxART_MY_ICON, wxART_MY_CLIENT);
|
||||
|
||||
Substitute wxART_MY_CLIENT in the example with a suitable client ID. If the
|
||||
client is wxART_OTHER you may write only
|
||||
|
||||
wxArtProvider::GetBitmap(wxART_MY_BITMAP).
|
||||
|
||||
3. Providing a demo
|
||||
-------------------
|
||||
|
||||
It is highly desirable to let the users know what stock bitmaps are available
|
||||
in wxWidgets. The "artprov" sample serves this purpose: it contains a browser
|
||||
dialog that displays all available art resources.
|
||||
|
||||
It has to be updated to accommodate for new bitmaps. Fortunately, this is
|
||||
trivial: open $(wx)/samples/artprov/artbrows.cpp in text editor and
|
||||
ART_ICON(wxART_MY_BITMAP) line to the FillBitmaps() function.
|
||||
|
||||
Similarly, if you add a new client, please update FillClients() by adding new
|
||||
client to the end of the list.
|
||||
|
||||
=== EOF ===
|
||||
|
||||
83
docs/contributing/how-to-add-new-wxUSE_XXX.txt
Normal file
83
docs/contributing/how-to-add-new-wxUSE_XXX.txt
Normal file
@ -0,0 +1,83 @@
|
||||
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. Files to update
|
||||
------------------
|
||||
|
||||
The following files need to be modified when adding a new wxUSE_FOO:
|
||||
|
||||
a) 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).
|
||||
|
||||
a') include/wx/msw/setup_inc.h for MSW-specific options
|
||||
|
||||
This file contains MSW-specific options, so if the new option is only used
|
||||
under MSW, add it here instead of include/wx/setup_inc.h. The rest of the
|
||||
instructions is the same as above.
|
||||
|
||||
b) include/wx/chkconf.h
|
||||
|
||||
Add the check for wxUSE_FOO definedness in the corresponding (base or GUI)
|
||||
section. Please keep the alphabetic order.
|
||||
|
||||
If there are any dependencies, i.e. wxUSE_FOO requires wxUSE_BAR and
|
||||
wxUSE_BAZ, check for thme here too.
|
||||
|
||||
b') include/wx/msw/chkconf.h for MSW-specific options
|
||||
|
||||
These options won't be defined for the other ports, so shouldn't be added to
|
||||
the common include/wx/chkconf.h but to this file instead.
|
||||
|
||||
c) 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.
|
||||
|
||||
d) docs/doxygen/mainpages/const_wxusedef.h
|
||||
|
||||
Add a brief description of the new constant.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
|
||||
54
docs/contributing/how-to-add-new-xrc-handler.txt
Normal file
54
docs/contributing/how-to-add-new-xrc-handler.txt
Normal file
@ -0,0 +1,54 @@
|
||||
How to add a new XRC handler
|
||||
============================
|
||||
|
||||
0. Purpose
|
||||
----------
|
||||
|
||||
This note describes what needs to be done to add a new XRC handler, i.e. add
|
||||
support for loading the objects of some class wxFoo from XRC.
|
||||
|
||||
|
||||
1. Implement the handler
|
||||
------------------------
|
||||
|
||||
By convention, the XRC handler for a class wxFoo declared in wx/foo.h is called
|
||||
wxFooXmlHandler and is declared in the file wx/xrc/xh_foo.h (this last rule
|
||||
wasn't always respected in the past, however it's not a reason to not respect
|
||||
it in the future). The steps for adding a new handler are:
|
||||
|
||||
a) Add handler declaration in include/wx/xrc/xh_foo.h, it will usually be the
|
||||
same as in the other files so you can get inspiration for your brand new
|
||||
handler from e.g. wx/xrc/xh_srchctrl.h. Notice the use of wxUSE_FOO if wxFoo
|
||||
is guarded by this symbol.
|
||||
|
||||
b) Add implementation in src/xrc/xh_foo.cpp: again, it will be almost always
|
||||
very similar to the existing controls. You will need to add support for
|
||||
the control-specific styles.
|
||||
|
||||
|
||||
2. Update the other files
|
||||
-------------------------
|
||||
|
||||
There are a few other files to update to make wxWidgets aware of the new
|
||||
handler:
|
||||
|
||||
a) Add the new files created above to build/bakefiles/files.bkl: search for
|
||||
"xh_srchctrl" to see where you need to add them
|
||||
|
||||
b) Add #include "wx/xrc/xh_foo.h" to wx/xrc/xh_all.h.
|
||||
|
||||
c) Register the new handler in wxXmlResource::InitAllHandlers() in
|
||||
src/xrc/xmlrsall.cpp
|
||||
|
||||
|
||||
3. Update the sample
|
||||
--------------------
|
||||
|
||||
Demonstrate that the new handler works by adding a control using it to
|
||||
samples/xrc/rc/controls.xrc.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
|
||||
180
docs/contributing/how-to-release.txt
Normal file
180
docs/contributing/how-to-release.txt
Normal file
@ -0,0 +1,180 @@
|
||||
Making a new wxWidgets release
|
||||
==============================
|
||||
|
||||
Before making the release
|
||||
-------------------------
|
||||
|
||||
Change the version in include/wx/version.h.
|
||||
|
||||
Update docs/readme.txt. Please review its contents in addition to just
|
||||
changing the version number.
|
||||
|
||||
Put a date on the release line in docs/changes.txt.
|
||||
|
||||
Update the date in the manual (docs/doxygen/mainpages/manual.h).
|
||||
|
||||
Update the release announcement post in docs/publicity/announce.txt.
|
||||
|
||||
|
||||
Creating release files
|
||||
----------------------
|
||||
|
||||
The currently used release scripts need to be used from git-svn checkout and
|
||||
rely on Git to avoid problems with using non-clean trees and such. If you don't
|
||||
use Git you may use the alternative archive creation scripts in the next
|
||||
section.
|
||||
|
||||
Follow these steps assuming the current working directory is the root of git
|
||||
working copy and you want to prepare distribution for the version x.y.z:
|
||||
|
||||
1. Run "./build/tools/svn-find-native-eols.pl > ../eol-native" (if you have
|
||||
an existing svn checkout, pass it to the script to make it run much faster,
|
||||
but take care to have up to date sources in the working tree).
|
||||
|
||||
2. Run "./build/tools/git-make-release x.y.z" to create source archives
|
||||
../wxWidgets-x.y.z.{7z,tar.bz2,zip} and wxWidgets_x.y.z_Headers.zip.
|
||||
|
||||
3. Run "./build/tools/make-html-docs x.y.z" to create HTML documentation
|
||||
archives ../wxWidgets-x.y.z.{tar.bz2,zip}
|
||||
|
||||
4. This step must be done under Windows as it relies on having hhc.exe, the
|
||||
Html Help compiler, in PATH: run the following commands
|
||||
|
||||
cd docs\doxygen
|
||||
regen.bat chm
|
||||
cd out
|
||||
zip ..\..\..\wxWidgets-x.y.z-docs-chm.zip wx.chm
|
||||
|
||||
5. This step also must be done under Windows as it uses Inno Setup to produce
|
||||
the .exe file and it also requires the CHM file built above:
|
||||
|
||||
md x.y.z-sources
|
||||
cd x.y.z-sources
|
||||
7z x ..\wxWidgets-x.y.z.7z
|
||||
md docs\htmlhelp
|
||||
cp ..\docs\doxygen\out\wx.chm docs\htmlhelp
|
||||
set WXW_VER=x.y.z
|
||||
iscc build\tools\wxwidgets.iss
|
||||
|
||||
|
||||
|
||||
Instructions for the previous version of release scripts
|
||||
--------------------------------------------------------
|
||||
|
||||
NB: These scripts haven't been used since 2.8 series and may not work any longer!
|
||||
|
||||
Currently our release system uses a Python 2.x script to generate releases.
|
||||
The script requires Unix utilities such as tar, zip and unix2dos and thus must
|
||||
be run either on Unix or using Cygwin on Windows. To generate a release, simply
|
||||
run the following command:
|
||||
|
||||
build/tools/create-archive.py --compression=all /path/to/output/dir
|
||||
|
||||
This will produce zip, gzip and bzip archives of the tree (without
|
||||
"compression" argument only .gz is made). Note that this commands produces huge
|
||||
amounts of output so redirecting it to a file is recommended.
|
||||
|
||||
To add a prefix to the release, such as RC1, the SVN revision, or a date, just
|
||||
pass --postfix="postfix" to the script. More info on the options and their
|
||||
possible values can be found by calling `create-archive.py --help`.
|
||||
|
||||
IMPORTANT NOTE: You *must* run this script from a clean source tree, that is,
|
||||
with no junk files in it or modifications. This is because the
|
||||
release should be a pristine copy of the tree as of the time of
|
||||
release. If you have legitimate modifications in the tree that need
|
||||
to be in the release, commit them first.
|
||||
|
||||
To generate the windows installer (.exe) and the documentation files (chm and htb formats)
|
||||
run:
|
||||
|
||||
build\tools\bld_chm_exe.bat
|
||||
|
||||
which depends on the wxwidgets.iss file, and generates output in the %DAILY% directory. It
|
||||
assumes a clean copy of the wxWidgets source tree in %INNO%. Temporary files will be generated
|
||||
in the tree from which the batch file is run. It depends on doxygen, a number of gnu
|
||||
win32 tools and Microsofts htmlhelp compiler. The wxwidgets.iss file should not need
|
||||
editing, but you will want to check that the bld_chm_exe.bat has the correct version number.
|
||||
|
||||
|
||||
|
||||
Uploading
|
||||
---------
|
||||
|
||||
Upload the files to SourceForge. This can be done via the web interface or just
|
||||
scp to sfusername,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z
|
||||
The following files need to be uploaded:
|
||||
|
||||
wxMSW-Setup-x.y.z.exe
|
||||
wxWidgets-x.y.z.7z
|
||||
wxWidgets-x.y.z.tar.bz2
|
||||
wxWidgets-x.y.z.zip
|
||||
wxWidgets-docs-chm-x.y.z.zip
|
||||
wxWidgets-docs-html-x.y.z.tar.bz2
|
||||
wxWidgets-docs-html-x.y.z.zip
|
||||
|
||||
The file wxWidgets-x.y.z_Headers.7z should be uploaded to binaries
|
||||
subdirectory as it's only useful when using pre-built binaries.
|
||||
|
||||
You will need to use the web interface to mark the latest uploaded files as
|
||||
being "default downloads" for the appropriate platforms (.zip or .exe for MSW,
|
||||
.tar.bz2 for everything else) as otherwise SourceForge would continue to suggest
|
||||
people to download old files.
|
||||
|
||||
Next, update (at least the versions and SHA1 sums, but maybe more) and upload
|
||||
docs/release_files.mdwn and docs/release_binaries.mdwn files. They need to be
|
||||
renamed to README.md on SF to be shown when the directory is viewed, i.e. do:
|
||||
|
||||
scp docs/release_files.mdwn \
|
||||
sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z/README.md
|
||||
scp docs/release_binaries.mdwn \
|
||||
sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z/binaries/README.md
|
||||
|
||||
And upload the change log too:
|
||||
|
||||
scp docs/changes.txt \
|
||||
sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z
|
||||
|
||||
|
||||
Also upload the files to the FTP mirror at ftp.wxwidgets.org (ask Chris for
|
||||
access if you don't have it).
|
||||
|
||||
Create http://docs.wxwidgets.org/x.y.z/ (ask Bryan to do it if not done yet).
|
||||
|
||||
|
||||
Announcement
|
||||
------------
|
||||
|
||||
Post docs/publicity/announce.txt at least to wx-announce@googlegroups.com and
|
||||
to wx-users for the important releases.
|
||||
|
||||
Submit a link to http://www.reddit.com/r/programming
|
||||
|
||||
Submit to http://isocpp.org/blog/suggest
|
||||
|
||||
For major releases, submit the announcement to http://slashdot.org/submission
|
||||
|
||||
Update www.wxwidgets.org, usually a news item is enough but something more can
|
||||
be called for for major releases.
|
||||
|
||||
Modify the links at downloads/index.html to point to the new release.
|
||||
|
||||
Also update docs/index.html for the minor or major (i.e. not micro) releases.
|
||||
|
||||
Post to wxBlog if necessary.
|
||||
|
||||
Announce on Google+/Twitter/whatever the person doing the release prefers (we
|
||||
don't have "official" wxWidgets account, should we?).
|
||||
|
||||
|
||||
Version updates
|
||||
---------------
|
||||
|
||||
Trac: mark the milestone corresponding to the release as completed and add a
|
||||
new version for it to allow reporting bugs against it and create the next
|
||||
milestone (ask Vadim or Robin to do it or to get admin password).
|
||||
|
||||
Run misc/scripts/inc_release to increment micro version, i.e. replace x.y.z
|
||||
with x.y.z+1 (minor or major versions updates require manual intervention).
|
||||
|
||||
Update the definition of the stable and release branches in
|
||||
build/buildbot/config/include/defs.xml after a minor version change.
|
||||
127
docs/contributing/how-to-update-third-party-library.txt
Normal file
127
docs/contributing/how-to-update-third-party-library.txt
Normal file
@ -0,0 +1,127 @@
|
||||
How to update a third party library to a newer version
|
||||
======================================================
|
||||
|
||||
0. Introduction
|
||||
---------------
|
||||
|
||||
wxWidgets includes several third party libraries, i.e. libraries which are
|
||||
used by wxWidgets and distributed with it but which we don't maintain nor even
|
||||
modify, inasmuch as possible, ourselves. These libraries are developed by
|
||||
their maintainers and from time to time we need to replace the versions used
|
||||
by wxWidgets with newer versions.
|
||||
|
||||
|
||||
1. Vendor branches
|
||||
------------------
|
||||
|
||||
Normally all third party libraries should be managed using Subversion vendor
|
||||
branches. I.e. we should have the latest version of the library under
|
||||
/wx/wxWidgets/vendor directory in the repository. Currently only expat, libpng
|
||||
and libtiff are handled like this, while libjpeg and zlib are not. Hopefully
|
||||
these exceptions will disappear soon, the rest of this note assumes that we
|
||||
are using a vendor branch for the library $(LIB).
|
||||
|
||||
We also use $(OLD_VERSION) and $(VERSION) below for the current version of the
|
||||
library and the version we are upgrading to. $(OLD_VERSION) can be determined
|
||||
by doing
|
||||
|
||||
svn ls https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)
|
||||
|
||||
as normally it's the latest version present in this directory. You can, of
|
||||
course, also look at the library sources currently in the trunk to find out
|
||||
its version.
|
||||
|
||||
|
||||
NB: the instructions here are based on the Subversion documentation, see
|
||||
http://svnbook.red-bean.com/en/1.6/svn.advanced.vendorbr.html for more
|
||||
information about vendor branches.
|
||||
|
||||
|
||||
2. Updating the current branch
|
||||
------------------------------
|
||||
|
||||
The first thing to do is to checkout a pristine copy of the version currently
|
||||
being used, e.g.
|
||||
|
||||
cd /some/temp/directory
|
||||
svn checkout https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current $(LIB)
|
||||
|
||||
Now delete all the old files:
|
||||
|
||||
cd $(LIB)
|
||||
find . -type f -not -path '*/.svn/*' -exec rm {} \;
|
||||
|
||||
or, if you are using zsh, just
|
||||
|
||||
rm **/*(.)
|
||||
|
||||
Next, get the version of the library you are updating to and unpack it into
|
||||
the same directory. Examine "svn status" output and add all the files with "?"
|
||||
in the first column using "svn add" and delete all the files with "!" in the
|
||||
first column using "svn rm".
|
||||
|
||||
Finally commit and tag the new version:
|
||||
|
||||
svn commit -m 'Update $(LIB) to $(VERSION).'
|
||||
svn cp https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current \
|
||||
https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/$(VERSION) \
|
||||
-m 'Tagging $(LIB) $(VERSION).'
|
||||
|
||||
You can now do
|
||||
|
||||
rm -rf /some/temp/directory/$(LIB)
|
||||
|
||||
as it won't be needed any longer.
|
||||
|
||||
|
||||
3. Merging the current branch
|
||||
-----------------------------
|
||||
|
||||
Now switch to wxWidgets checkout and run
|
||||
|
||||
svn merge ^/wxWidgets/vendor/$(LIB)/$(OLD_VERSION) ^/wxWidgets/vendor/$(LIB)/current src/$(LIBDIR)
|
||||
|
||||
Notice that you may need to escape the circumflexes with backslashes if they
|
||||
are special for your shell. Also notice that the directory of the library may
|
||||
be different from its name, e.g. we use libpng for the vendor branch but just
|
||||
png for the name of the directory.
|
||||
|
||||
Unless you are very lucky, the merge will result in conflicts and you will
|
||||
need to resolve them by examining the differences -- this is the difficult
|
||||
part.
|
||||
|
||||
Once everything was resolved, test your changes. As building the third party
|
||||
libraries is quite different between Unix and Windows, please do it under both
|
||||
platforms. Under Windows it's enough to just build everything as usual as the
|
||||
built-in libraries are used by default. Please build both static and dynamic
|
||||
wxWidgets libraries as some problems arise only in one of those configurations.
|
||||
Under Unix you need to configure with --with-$(LIB)=builtin option to ensure
|
||||
that the newly updated built-in version of the library is used and not the
|
||||
system version. If upgrading an image format library, please build and run the
|
||||
image sample. In any case, run the unit tests to check that everything still
|
||||
works.
|
||||
|
||||
After testing and correcting the problems, simply commit your changes:
|
||||
|
||||
svn commit -m 'Update $(LIB) to $(VERSION).' src/$(LIBDIR)
|
||||
|
||||
|
||||
4. Special instructions for libpng
|
||||
----------------------------------
|
||||
|
||||
We use a special hack for libpng as we want to prefix all its symbols with
|
||||
"wx_" but don't want to use its build system which makes this easily possible
|
||||
(perhaps we should, but for now we don't). So, when upgrading libpng, you need
|
||||
to perform an extra step after merging the new version (and before committing
|
||||
your changes):
|
||||
|
||||
Create a temporary build directory and run libpng configure from it using
|
||||
--with-libpng-prefix=wx_ option. Then run "make" (actually just "make png.lo"
|
||||
is sufficient as we don't really need to build the library) to create
|
||||
pnglibconf.h and pngprefix.h files in the build directory. And copy these
|
||||
files to src/png subdirectory of the wxWidgets source tree, overwriting the
|
||||
versions there.
|
||||
|
||||
Notice that config.h generated by libpng configure is not used, we build it
|
||||
without -DHAVE_CONFIG_H as it works just fine without it on any ANSI C system
|
||||
(i.e. anywhere by now).
|
||||
144
docs/contributing/how-to-write-unit-tests.txt
Normal file
144
docs/contributing/how-to-write-unit-tests.txt
Normal file
@ -0,0 +1,144 @@
|
||||
How to write unit tests for wxWidgets
|
||||
=====================================
|
||||
|
||||
Unit tests for wxWidgets are written using small cppunit framework. To compile
|
||||
(but not to run) them you need to have it installed. Hence the first part of
|
||||
this note explains how to do it while the second one explains how to write the
|
||||
test.
|
||||
|
||||
I. CppUnit Installation
|
||||
-----------------------
|
||||
|
||||
1. Get it from http://www.sourceforge.net/projects/cppunit
|
||||
(latest version as of the time of this writing is 1.10.2)
|
||||
|
||||
2. Build the library:
|
||||
a) Under Windows using VC++:
|
||||
- build everything in CppUnitLibraries.dsw work space
|
||||
- add include and lib subdirectories of the directory
|
||||
where you installed cppunit to the compiler search path
|
||||
using "Tools|Options" menu in VC IDE
|
||||
|
||||
b) Under Unix: run configure && make && make install as usual
|
||||
|
||||
|
||||
II. Writing tests with CppUnit
|
||||
------------------------------
|
||||
|
||||
1. Create a new directory tests/foo
|
||||
|
||||
2. Write a cpp file for the test copying, if you want,
|
||||
from one of the existing tests. The things to look for:
|
||||
a) #include "wx/cppunit.h" instead of directly including CppUnit headers
|
||||
b) don't put too many things in one test case nor in one method of a test
|
||||
case as it makes understanding what exactly failed harder later
|
||||
c) 'register' your tests as follows so that the test program will find and
|
||||
execute them:
|
||||
|
||||
// register in the unnamed registry so that these tests are run by default
|
||||
CPPUNIT_TEST_SUITE_REGISTRATION(MBConvTestCase);
|
||||
|
||||
// also include in its own registry so that these tests can be run alone
|
||||
CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(MBConvTestCase, "MBConvTestCase");
|
||||
|
||||
Read CppUnit documentation for more.
|
||||
d) wxUIActionSimulator can be used when user input is required, for example
|
||||
clicking buttons or typing text. A simple example of this can be found
|
||||
in controls/buttontest.cpp. After simulating some user input always
|
||||
wxYield to allow event processing. When writing a test using
|
||||
wxUIActionSimulator always add the test using WXUISIM_TEST rather than
|
||||
CPPUNIT_TEST as then it won't run on unsupported platforms. The test itself
|
||||
must also be wrapped in a #if wxUSE_UIACTIONSIMULATOR block.
|
||||
e) There are a number of classes that are available to help with testing GUI
|
||||
elements. Firstly throughout the test run there is a frame of type
|
||||
wxTestableFrame that you can access through wxTheApp->GetTopWindow(). This
|
||||
class adds two new functions, GetEventCount, which takes an optional
|
||||
wxEventType. It then returns the number of events of that type that it has
|
||||
received since the last call. Passing nothing returns the total number of
|
||||
event received since the last call. Also there is OnEvent, which counts the
|
||||
events based on type that are passed to it. To make it easy to count events
|
||||
there is also a new class called EventCounter which takes a window and event
|
||||
type and connects the window to the top level wxTestableFrame with the specific
|
||||
event type. It disconnects again once it is out of scope. It simply reduces
|
||||
the amount of typing required to count events.
|
||||
|
||||
3. add a '<sources>' tag for your source file to tests/test.bkl. Make sure it's
|
||||
in the correct section: the one starting '<exe id="test_gui"' for a gui test,
|
||||
the one starting '<exe id="test" template="wx_sample_console' otherwise.
|
||||
|
||||
|
||||
III. Running the tests
|
||||
----------------------
|
||||
|
||||
1. Regenerate the make/project files from test.bkl using bakefile_gen, e.g.:
|
||||
cd build/bakefiles
|
||||
bakefile_gen -b ../../tests/test.bkl
|
||||
and if you're on a unix system re-run configure.
|
||||
|
||||
2. Build the test program using one of the make/project files in the tests
|
||||
subdirectory.
|
||||
|
||||
3. Run the test program by using the command 'test' for the console tests,
|
||||
'test_gui' for the gui ones. With no arguments, all the default set of tests
|
||||
(all those registered with CPPUNIT_TEST_SUITE_REGISTRATION) are run.
|
||||
Or to list the test suites without running them:
|
||||
test -l or test_gui -l
|
||||
|
||||
4. Tests that have been registered under a name using
|
||||
CPPUNIT_TEST_SUITE_NAMED_REGISTRATION can also be run separately. For
|
||||
example:
|
||||
test_gui ButtonTestCase
|
||||
or to list the tests done by a particular testcase:
|
||||
test -L MBConvTestCase
|
||||
|
||||
5. Fault navigation.
|
||||
VC++ users can run the programs as a post build step (Projects/Settings/
|
||||
Post-build step) to see the test results in an IDE window. This allows
|
||||
errors to be jumped to in the same way as for compiler errors, for
|
||||
example by pressing F4 or highlighting the error and pressing return.
|
||||
|
||||
Similarly for makefile users: makefiles can be modified to execute the
|
||||
test programs as a final step. Then you can navigate to any errors in the
|
||||
same way as for compiler errors, if your editor supports that.
|
||||
|
||||
Another alternative is to run the tests manually, redirecting the output
|
||||
to a file. Then use your editor to jump to any failures. Using Vim, for
|
||||
example, ':cf test.log' would take you to the first error in test.log, and
|
||||
':cn' to the next.
|
||||
|
||||
If you would like to set a breakpoint on a failing test using a debugger,
|
||||
put the breakpoint on the function 'CppUnit::Asserter::fail()'. This will
|
||||
stop on each failing test.
|
||||
|
||||
|
||||
IV. Notes
|
||||
---------
|
||||
|
||||
1. You can register your tests (or a subset of them) just under a name, and not
|
||||
in the unnamed registry if you don't want them to be executed by default.
|
||||
|
||||
2. If you are going to register your tests both in the unnamed registry
|
||||
and under a name, then use the name that the tests have in the 'test -l'
|
||||
listing.
|
||||
|
||||
3. Tests which fail can be temporarily registered under "fixme" while the
|
||||
problems they expose are fixed, instead of the unnamed registry. That
|
||||
way they can easily be run, but they do not make regression testing with
|
||||
the default suite more difficult. E.g.:
|
||||
|
||||
// register in the unnamed registry so that these tests are run by default
|
||||
//CPPUNIT_TEST_SUITE_REGISTRATION(wxRegExTestCase);
|
||||
CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "fixme");
|
||||
|
||||
// also include in its own registry so that these tests can be run alone
|
||||
CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "wxRegExTestCase");
|
||||
|
||||
4. Tests which take a long time to execute can be registered under "advanced"
|
||||
instead of the unnamed registry. The default suite should execute reasonably
|
||||
quickly. To run the default and advanced tests together:
|
||||
test "" advanced
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ & MW
|
||||
102
docs/contributing/translators-guide.txt
Normal file
102
docs/contributing/translators-guide.txt
Normal file
@ -0,0 +1,102 @@
|
||||
wxWidgets translator guide
|
||||
==========================
|
||||
|
||||
This note is addressed to wxWidgets translators.
|
||||
|
||||
First of all, here is what you will need:
|
||||
|
||||
1. GNU gettext package version 0.10.35 or later (NB: earlier versions were
|
||||
known to have serious bugs)
|
||||
|
||||
a) for Unix systems you can download gettext-0.10.tar.gz from any GNU
|
||||
mirror (RPMs and DEBs are also available from the usual places)
|
||||
|
||||
b) for Windows you can download the precompiled binaries from
|
||||
www.wxwidgets.org or install PoEdit (poedit.sourceforge.net) and
|
||||
add <installdir>/poEdit/bin to your path (so it can find xgettext).
|
||||
|
||||
2. A way to run a program recursively on an entire directory from the command
|
||||
line:
|
||||
|
||||
a) for Unix systems, this is done in locale/Makefile using the standard find
|
||||
command and xargs which is installed on almost all modern Unices. If you
|
||||
are unlucky enough to not have xargs, you can use the -exec option of find
|
||||
instead.
|
||||
|
||||
b) for Win32 systems you can use either Cygwin or MinGW. If you don't have
|
||||
those it is less trivial: if you have 4DOS/4NT/bash, that's
|
||||
fine, but you'd have to use some kind of "for /s" loop with the
|
||||
command.com/cmd.exe.
|
||||
|
||||
3. (at least read) access to the subversion is not necessary strictly speaking, but
|
||||
will make things a lot easier for you and others.
|
||||
|
||||
|
||||
Now a brief overview of the process of translations (please refer to GNU
|
||||
gettext documentation for more details). It happens in several steps:
|
||||
|
||||
1. the strings to translate are extracted from the C++ sources using xgettext
|
||||
program into a wxstd.pot file which is a "text message catalog"
|
||||
|
||||
2. this new wxstd.pot file (recreated each time some new text messages are added
|
||||
to wxWidgets) is merged with existing translations in another .po file (for
|
||||
example, de.po) and replaces this file (this is done using the program
|
||||
msgmerge)
|
||||
|
||||
3. the resulting .po file must be translated
|
||||
|
||||
4. finally, msgformat must be run to produce a .mo file: "binary message catalog"
|
||||
|
||||
|
||||
How does it happen in practice? There is a Makefile in the "locale"
|
||||
directory which will do almost everything (except translations) for you. i.e.
|
||||
just type "make lang.po" to create or update the message catalog for 'lang'.
|
||||
Then edit the resulting lang.po and make sure that there are no empty or fuzzy
|
||||
translations left (empty translations are the ones with msgstr "", fuzzy
|
||||
translations are those which have the word "fuzzy" in a comment just above
|
||||
them). Then type "make lang.mo" which will create the binary message catalog.
|
||||
|
||||
Under Windows (If you don't have Cygwin or MinGW), you should execute the
|
||||
commands manually, please have a look at Makefile to see what must be done.
|
||||
|
||||
For platform specific translations, .po files such as 'locale/msw/it.po' can be
|
||||
used to provide translations that override the usual ones in 'locale/it.po'.
|
||||
The generated .mo files are then installed under the names such as 'wxmsw.mo'
|
||||
alongside the generic 'wxstd.mo'.
|
||||
|
||||
A new platform specific translation should be added to a section such as this
|
||||
in wx.bkl:
|
||||
|
||||
<gettext-catalogs id="locale_msw">
|
||||
<srcdir>$(SRCDIR)/locale/msw</srcdir>
|
||||
<catalog-name>wxmsw</catalog-name>
|
||||
<linguas>it</linguas>
|
||||
<install-to>$(LOCALEDIR)</install-to>
|
||||
</gettext-catalogs>
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
|
||||
$Log$
|
||||
Revision 1.7 2005/08/12 15:34:01 MW
|
||||
Typo
|
||||
|
||||
Revision 1.6 2005/08/12 15:29:47 MW
|
||||
Translate '&Help' to '&' for italian Windows only
|
||||
|
||||
Revision 1.5 2004/10/22 19:12:59 KH
|
||||
*** empty log message ***
|
||||
|
||||
Revision 1.4 2004/05/04 08:26:58 JS
|
||||
Name change replacements
|
||||
|
||||
Revision 1.3 2003/11/18 16:37:11 DS
|
||||
Updated translation technote to mention Makefile usage under Windows.
|
||||
|
||||
Revision 1.2 2002/07/03 15:01:26 VZ
|
||||
typos and other doc corrections from Olly Betts (patch 573738)
|
||||
|
||||
Revision 1.1 2000/03/07 10:53:53 VZ
|
||||
technote about translations added
|
||||
|
||||
53
docs/contributing/wxmsw-contributor-guide.txt
Normal file
53
docs/contributing/wxmsw-contributor-guide.txt
Normal file
@ -0,0 +1,53 @@
|
||||
Special notes about writing wxMSW code
|
||||
======================================
|
||||
|
||||
0. Purpose
|
||||
----------
|
||||
|
||||
This is just a collection of various notes which should be useful to anybody
|
||||
working on wxMSW codebase, please feel free to add more here.
|
||||
|
||||
This text assumes familiarity with both Windows programming and wxWidgets so it
|
||||
doesn't cover any wxWidgets-wide issues not specific to Windows.
|
||||
|
||||
|
||||
1. Windows headers wrappers
|
||||
---------------------------
|
||||
|
||||
In no event should the Windows headers such as <windows.h> or <commctrl.h> be
|
||||
included directly. So instead of #include <...> use "wx/msw/wrapwin.h" or
|
||||
"wx/msw/wrapcctl.h".
|
||||
|
||||
For convenience it is also possible to replace #include <commdlg.h> and
|
||||
<shlobj.h> with #include "wx/msw/wrapcdlg.h" and wrapshl.h but this is less
|
||||
vital.
|
||||
|
||||
Also notice that many convenient (albeit undocumented) functions and classes
|
||||
are declared in "wx/msw/private.h", please do become familiar with this file
|
||||
contents and use the utility classes and functions from it instead of
|
||||
duplicating their functionality (which can often be done only in exception
|
||||
unsafe way).
|
||||
|
||||
|
||||
2. Windows features checks
|
||||
--------------------------
|
||||
|
||||
All checks of features not present in all Windows versions must be done both at
|
||||
compile-time (because, even though we use maximal value for WINVER in our code,
|
||||
some compilers come with headers too old to declare them) and at run-time
|
||||
(because wxMSW applications should run everywhere).
|
||||
|
||||
The functions wxGetWinVersion() (from wx/msw/private.h) and wxApp::
|
||||
GetComCtl32Version() should be used to check Windows and comctl32.dll versions
|
||||
respectively.
|
||||
|
||||
Any functions which may not be present in kernel32.dll/user32.dll/... in all
|
||||
Windows versions should be resolved dynamically, i.e. using wxDynamicLibrary as
|
||||
otherwise any wx application -- even not needing them at all -- would refuse to
|
||||
start up on Windows versions not implementing the feature in question. As an
|
||||
example, look at AlphaBlt()-related code in src/msw/dc.cpp.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
@ -1,29 +1,31 @@
|
||||
All wxWidgets technical notes at a glance
|
||||
=========================================
|
||||
All the files in this directory are obsolete (including this one) and are kept
|
||||
just to avoid breaking the existing links to them, please refer to the files
|
||||
with the corresponding name under docs/contributing instead:
|
||||
|
||||
tn0001.txt How to add a new sample
|
||||
tn0002.txt wxWidgets translator guide
|
||||
tn0003.txt Adding wxWidgets class documentation
|
||||
tn0004.htm *** REMOVED *** (obsoleted by Bakefile changes)
|
||||
tn0005.txt Adding a wxWidgets contribution
|
||||
tn0006.txt *** REMOVED *** (obsoleted by tn0013.txt)
|
||||
tn0007.txt *** REMOVED *** (obsoleted by Bakefile changes)
|
||||
tn0008.htm *** REMOVED *** (included in the manual now)
|
||||
tn0009.htm Creating and converting icons
|
||||
tn0010.htm *** REMOVED *** (obsoleted by Bakefile changes)
|
||||
tn0011.txt All about version numbers
|
||||
tn0012.txt wxWidgets platform, toolkit and library names
|
||||
tn0013.txt *** REMOVED *** (obsoleted by tn0022.txt)
|
||||
tn0014.txt *** REMOVED *** (included in the manual now)
|
||||
tn0015.txt How to add new bitmaps to wxWidgets UI elements
|
||||
tn0016.txt How to add new files and libraries to wxWidgets build system (Bakefile)
|
||||
tn0017.txt How to write unit tests for wxWidgets classes
|
||||
tn0018.txt How to add a new font encoding/charset to wxWidgets
|
||||
tn0019.txt Special notes about writing wxMSW code
|
||||
tn0020.txt Binary compatibility and wxWidgets
|
||||
tn0021.txt How to add a new wxUSE_XXX preprocessor constant
|
||||
tn0022.txt Making a new release
|
||||
tn0023.txt Adding a new app/screenshot to the wxWidgets.org front page
|
||||
tn0024.txt How to add a new XRC handler
|
||||
tn0025.txt How to update a third party library to a newer version
|
||||
|
||||
tn0001.txt -> docs/contributing/how-to-add-new-sample.txt
|
||||
tn0002.txt -> docs/contributing/translators-guide.txt
|
||||
tn0003.txt -> docs/contributing/how-to-add-class-documentation.txt
|
||||
tn0004.htm -> *** REMOVED *** (obsoleted by Bakefile changes)
|
||||
tn0005.txt -> *** REMOVED *** (obsoleted by http://wiki.wxwidgets.org/Development:_How_To_Contribute)
|
||||
tn0006.txt -> *** REMOVED *** (obsoleted by tn0013.txt)
|
||||
tn0007.txt -> *** REMOVED *** (obsoleted by Bakefile changes)
|
||||
tn0008.htm -> *** REMOVED *** (included in the manual now)
|
||||
tn0009.htm -> *** REMOVED *** (use any standard tool for icon creation)
|
||||
tn0010.htm -> *** REMOVED *** (obsoleted by Bakefile changes)
|
||||
tn0011.txt -> docs/contributing/about-version-numbers.txt
|
||||
tn0012.txt -> docs/contributing/about-platform-toolkit-and-library-names.txt
|
||||
tn0013.txt -> *** REMOVED *** (obsoleted by tn0022.txt)
|
||||
tn0014.txt -> *** REMOVED *** (included in the manual now)
|
||||
tn0015.txt -> docs/contributing/how-to-add-new-ui-bitmaps.txt
|
||||
tn0016.txt -> docs/contributing/how-to-add-files-to-build-system.txt
|
||||
tn0017.txt -> docs/contributing/how-to-write-unit-tests.txt
|
||||
tn0018.txt -> docs/contributing/how-to-add-new-font-encoding.txt
|
||||
tn0019.txt -> docs/contributing/wxmsw-contributor-guide.txt
|
||||
tn0020.txt -> docs/contributing/binary-compatibility.txt
|
||||
tn0021.txt -> docs/contributing/how-to-add-new-wxUSE_XXX.txt
|
||||
tn0022.txt -> docs/contributing/how-to-release.txt
|
||||
tn0023.txt -> *** REMOVED *** (obsoleted by web site redesign)
|
||||
tn0024.txt -> docs/contributing/how-to-add-new-xrc-handler.txt
|
||||
tn0025.txt -> docs/contributing/how-to-update-third-party-library.txt
|
||||
|
||||
|
||||
@ -1,59 +1 @@
|
||||
How to add a new sample to wxWidgets.
|
||||
=====================================
|
||||
|
||||
To add a new sample "foo" under directory "samples/foo" you need to do
|
||||
the following: (note that all this applies also to demos: just replace
|
||||
samples/ with demos/ where needed).
|
||||
|
||||
1. Create the directory samples/foo locally and "svn add" it.
|
||||
|
||||
2. "svn 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.*
|
||||
files in the samples subdirectory.
|
||||
|
||||
3. Create the makefiles:
|
||||
a) modify samples/samples.bkl (just copy an existing line)
|
||||
b) create foo.bkl (sed 's/minimal/foo/g' minimal.bkl > foo.bkl is usually
|
||||
enough, but you may need to add more <wx-lib> lines if your sample uses
|
||||
anything not in the core lib)
|
||||
c) generate the makefiles for your sample using bakefile. For this you
|
||||
need to:
|
||||
(i) install bakefile (see http://bakefile.sf.net/)
|
||||
(ii) 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<compiler>" to generate just the makefiles for the given
|
||||
compiler (run 'bakefile --help' to get the list of possible values).
|
||||
See Technote #16 for more information.
|
||||
d) currently samples/samples.dsw needs to be updated manually as it's not
|
||||
generated by bakefile.
|
||||
|
||||
4. Modify configure.in Unix compilation:
|
||||
a) 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)
|
||||
|
||||
After this, regenerate configure from configure.in
|
||||
by running "autoconf" on a Unix system in the corresponding directory.
|
||||
|
||||
5. 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
|
||||
other samples, if you are not familiar with Doxygen.
|
||||
|
||||
6. 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).
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
Please see index.txt
|
||||
|
||||
@ -1,102 +1 @@
|
||||
wxWidgets translator guide
|
||||
==========================
|
||||
|
||||
This note is addressed to wxWidgets translators.
|
||||
|
||||
First of all, here is what you will need:
|
||||
|
||||
1. GNU gettext package version 0.10.35 or later (NB: earlier versions were
|
||||
known to have serious bugs)
|
||||
|
||||
a) for Unix systems you can download gettext-0.10.tar.gz from any GNU
|
||||
mirror (RPMs and DEBs are also available from the usual places)
|
||||
|
||||
b) for Windows you can download the precompiled binaries from
|
||||
www.wxwidgets.org or install PoEdit (poedit.sourceforge.net) and
|
||||
add <installdir>/poEdit/bin to your path (so it can find xgettext).
|
||||
|
||||
2. A way to run a program recursively on an entire directory from the command
|
||||
line:
|
||||
|
||||
a) for Unix systems, this is done in locale/Makefile using the standard find
|
||||
command and xargs which is installed on almost all modern Unices. If you
|
||||
are unlucky enough to not have xargs, you can use the -exec option of find
|
||||
instead.
|
||||
|
||||
b) for Win32 systems you can use either Cygwin or MinGW. If you don't have
|
||||
those it is less trivial: if you have 4DOS/4NT/bash, that's
|
||||
fine, but you'd have to use some kind of "for /s" loop with the
|
||||
command.com/cmd.exe.
|
||||
|
||||
3. (at least read) access to the subversion is not necessary strictly speaking, but
|
||||
will make things a lot easier for you and others.
|
||||
|
||||
|
||||
Now a brief overview of the process of translations (please refer to GNU
|
||||
gettext documentation for more details). It happens in several steps:
|
||||
|
||||
1. the strings to translate are extracted from the C++ sources using xgettext
|
||||
program into a wxstd.pot file which is a "text message catalog"
|
||||
|
||||
2. this new wxstd.pot file (recreated each time some new text messages are added
|
||||
to wxWidgets) is merged with existing translations in another .po file (for
|
||||
example, de.po) and replaces this file (this is done using the program
|
||||
msgmerge)
|
||||
|
||||
3. the resulting .po file must be translated
|
||||
|
||||
4. finally, msgformat must be run to produce a .mo file: "binary message catalog"
|
||||
|
||||
|
||||
How does it happen in practice? There is a Makefile in the "locale"
|
||||
directory which will do almost everything (except translations) for you. i.e.
|
||||
just type "make lang.po" to create or update the message catalog for 'lang'.
|
||||
Then edit the resulting lang.po and make sure that there are no empty or fuzzy
|
||||
translations left (empty translations are the ones with msgstr "", fuzzy
|
||||
translations are those which have the word "fuzzy" in a comment just above
|
||||
them). Then type "make lang.mo" which will create the binary message catalog.
|
||||
|
||||
Under Windows (If you don't have Cygwin or MinGW), you should execute the
|
||||
commands manually, please have a look at Makefile to see what must be done.
|
||||
|
||||
For platform specific translations, .po files such as 'locale/msw/it.po' can be
|
||||
used to provide translations that override the usual ones in 'locale/it.po'.
|
||||
The generated .mo files are then installed under the names such as 'wxmsw.mo'
|
||||
alongside the generic 'wxstd.mo'.
|
||||
|
||||
A new platform specific translation should be added to a section such as this
|
||||
in wx.bkl:
|
||||
|
||||
<gettext-catalogs id="locale_msw">
|
||||
<srcdir>$(SRCDIR)/locale/msw</srcdir>
|
||||
<catalog-name>wxmsw</catalog-name>
|
||||
<linguas>it</linguas>
|
||||
<install-to>$(LOCALEDIR)</install-to>
|
||||
</gettext-catalogs>
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
|
||||
$Log$
|
||||
Revision 1.7 2005/08/12 15:34:01 MW
|
||||
Typo
|
||||
|
||||
Revision 1.6 2005/08/12 15:29:47 MW
|
||||
Translate '&Help' to '&' for italian Windows only
|
||||
|
||||
Revision 1.5 2004/10/22 19:12:59 KH
|
||||
*** empty log message ***
|
||||
|
||||
Revision 1.4 2004/05/04 08:26:58 JS
|
||||
Name change replacements
|
||||
|
||||
Revision 1.3 2003/11/18 16:37:11 DS
|
||||
Updated translation technote to mention Makefile usage under Windows.
|
||||
|
||||
Revision 1.2 2002/07/03 15:01:26 VZ
|
||||
typos and other doc corrections from Olly Betts (patch 573738)
|
||||
|
||||
Revision 1.1 2000/03/07 10:53:53 VZ
|
||||
technote about translations added
|
||||
|
||||
Please see index.txt
|
||||
|
||||
@ -1,315 +1 @@
|
||||
Adding wxWidgets class documentation
|
||||
====================================
|
||||
|
||||
This note is aimed at people wishing to add documentation for a
|
||||
class to either the main wxWidgets manual, or to their own
|
||||
manual.
|
||||
|
||||
wxWidgets uses Doxygen to process header input files with embedded
|
||||
documentation in the form of C++ comments and output in HTML, and XML
|
||||
(Doxygen itself can also output Latex, manpages, RTF, PDF etc).
|
||||
See http://www.doxygen.org for more info about Doxygen.
|
||||
|
||||
If you want to add documentation of a new class/function to the
|
||||
existing manual in docs/doxygen, you need to create a new .h file,
|
||||
e.g. myclass.h, under the interface folder, which contains the public
|
||||
interface of the new class/function in C++ syntax.
|
||||
The documentation can then be added in form of Doxygen comments to
|
||||
the header file.
|
||||
|
||||
You may also want to write a separate topic file,
|
||||
e.g. docs/doxygen/overviews/myclass.h, and add the entry to
|
||||
docs/doxygen/mainpages/topics.h.
|
||||
|
||||
If applicable, also add an entry to one of the docs/doxygen/mainpages/cat_*.h
|
||||
files.
|
||||
|
||||
You can generate a first raw version of myclass.h simply taking its
|
||||
"real" header and removing all the private and protected sections and
|
||||
in general removing everything the user "shouldn't know": i.e. all things
|
||||
which are implementation details.
|
||||
|
||||
|
||||
Running Doxygen
|
||||
===============
|
||||
|
||||
First, make sure you have a recent version of Doxygen installed in your system
|
||||
(you'll need Doxygen >= 1.5.7).
|
||||
|
||||
On Unix:
|
||||
|
||||
1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate]
|
||||
|
||||
On Windows:
|
||||
1) cd wxWidgets/docs/doxygen
|
||||
2) run regen.bat [format-to-generate]
|
||||
|
||||
If you don't specify which format to [re]generate, all output formats will
|
||||
be enabled. Possible values for [format-to-generate] are: "html", "chm", "latex",
|
||||
"xml" and "all".
|
||||
|
||||
The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder.
|
||||
|
||||
|
||||
Important Dos and Don'ts
|
||||
========================
|
||||
|
||||
DO:
|
||||
|
||||
- Doxygen supports both commands in the form \command and @command;
|
||||
all wxWidgets documentation uses the @command form.
|
||||
Follow strictly this rule.
|
||||
|
||||
- strive to use dedicated Doxygen commands for e.g. notes, lists,
|
||||
sections, etc. The "Special commands" page:
|
||||
http://www.stack.nl/~dimitri/doxygen/commands.html
|
||||
is your friend!
|
||||
It's also very important to make a consistent use of the ALIASES
|
||||
defined by wxWidgets' Doxyfile. Open that file for more info.
|
||||
|
||||
- when you write true, false and NULL with their C++ semantic meaning,
|
||||
then use the @true, @false and @NULL commands.
|
||||
|
||||
- separate different paragraphs with an empty comment line.
|
||||
This is important otherwise Doxygen puts everything in the same
|
||||
paragraph making the result less readable.
|
||||
|
||||
- leave a blank comment line between a @section, @subsection, @page
|
||||
and the next paragraph.
|
||||
|
||||
- test your changes, both reading the generated HTML docs and by looking
|
||||
at the "doxygen.log" file produced (which will warn you about any
|
||||
eventual mistake found in the comments).
|
||||
|
||||
- quote all the following characters prefixing them with a "@" char:
|
||||
|
||||
@ $ \ & < > # %
|
||||
|
||||
unless they appear inside a @code or @verbatim section
|
||||
(you can also use HTML-style escaping, e.g. & rather than @ escaping)
|
||||
|
||||
- when using a Doxygen alias like @itemdef{}, you need to escape the
|
||||
comma characters which appear on the first argument, otherwise Doxygen
|
||||
will interpret them as the marker of the end of the first argument and
|
||||
the beginning of the second argument's text.
|
||||
|
||||
E.g. if you want to define the item "wxEVT_MACRO(id, func)" you need to
|
||||
write:
|
||||
@itemdef{wxEVT_MACRO(id\, func), This is the description of the macro}
|
||||
|
||||
Also note that you need to escape only the commas of the first argument's
|
||||
text; second argument can have up to 10 commas unescaped (see the Doxyfile
|
||||
for the trick used to implement this).
|
||||
|
||||
- for linking use one of:
|
||||
=> the @ref command to refer to topic overviews;
|
||||
=> the () suffix to refer to function members of the same class you're
|
||||
documenting or to refer to global functions or macros;
|
||||
=> the classname:: operator to refer to functions of classes different
|
||||
from the one you're documenting;
|
||||
=> the :: prefix to refer to global variables (e.g. ::wxEmptyString).
|
||||
Class names are auto-linked by Doxygen without the need of any explicit
|
||||
command.
|
||||
|
||||
DON'T:
|
||||
|
||||
- use jargon, such as 'gonna', or omit the definite article.
|
||||
The manual is intended to be a fluent, English document and
|
||||
not a collection of rough notes.
|
||||
|
||||
- use non-alphanumeric characters in link anchors.
|
||||
|
||||
- use Doxygen @b @c @e commands when referring to more than a single word;
|
||||
in that case you need to use the <b>...</b>, <tt>...</tt>, <em>...</em>
|
||||
HTML-style tags instead
|
||||
|
||||
- use HTML style tags for creation of tables or lists.
|
||||
Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and
|
||||
@beginDefList, @itemdef, @endDefList, etc.
|
||||
See the Doxyfile.inc for more info.
|
||||
|
||||
|
||||
Documentation comment for a class
|
||||
=================================
|
||||
|
||||
Start off with:
|
||||
|
||||
/**
|
||||
@class wxMyClass
|
||||
|
||||
...here goes the description...
|
||||
|
||||
@beginEventTable
|
||||
@event{EVT_SOME_EVENT(id, func)}:
|
||||
Description for EVT_SOME_EVENT.
|
||||
@endEventTable
|
||||
|
||||
@beginStyleTable
|
||||
@style{wxSOME_STYLE}:
|
||||
Description for wxSOME_STYLE.
|
||||
...
|
||||
@endStyleTable
|
||||
|
||||
@beginExtraStyleTable
|
||||
@style{wxSOME_EXTRA_STYLE}:
|
||||
Description for wxSOME_EXTRA_STYLE.
|
||||
...
|
||||
@endExtraStyleTable
|
||||
|
||||
@library{wxbase}
|
||||
@category{cat_shortcut}
|
||||
|
||||
@nativeimpl{wxgtk, wxmsw, ...}
|
||||
@onlyfor{wxgtk, wxmsw, ...}
|
||||
|
||||
@appearance{button.png}
|
||||
|
||||
@stdobjects
|
||||
...here goes the list of predefined instances...
|
||||
|
||||
@see ...here goes the see-also list...
|
||||
you can make references to topic overviews or other
|
||||
manual pages using the @ref command
|
||||
*/
|
||||
|
||||
Note that everything *except* the @class, @library and @category
|
||||
commands are optionals.
|
||||
|
||||
Also note that if you use @section and @subsection in the class description
|
||||
(at the beginning), you should use as the section's anchor name "xxxx_yyyy"
|
||||
where "xxxx" is the class name without the initial "wx" in lowercase
|
||||
and "yyyy" is a lowercase word which uniquely identifies that section.
|
||||
E.g.:
|
||||
|
||||
/**
|
||||
@class wxMyClass
|
||||
|
||||
This class does not exist really and is only used as an example
|
||||
of best documentation practices.
|
||||
|
||||
@section myclass_special Special functions of this class
|
||||
|
||||
This section describes the functions whose usage is reserved for
|
||||
wxWidgets internal mechanisms... etc etc...
|
||||
|
||||
|
||||
@section myclass_custom Customizing wxMyClass
|
||||
|
||||
What if you want to customize this powerful class?
|
||||
First you should do this and that, etc etc...
|
||||
|
||||
|
||||
@library{wxbase}
|
||||
@category{misc}
|
||||
|
||||
@see wxMyOtherClass
|
||||
*/
|
||||
|
||||
|
||||
|
||||
Documentation comment for a function
|
||||
====================================
|
||||
|
||||
Start off with:
|
||||
|
||||
/**
|
||||
...here goes the description of the function....
|
||||
|
||||
@param param1
|
||||
...here goes the description for the first parameter of this function
|
||||
@param param2
|
||||
...here goes the description for the second parameter of this function
|
||||
...
|
||||
|
||||
@return
|
||||
...here goes the description of what the function returns...
|
||||
|
||||
@note ...here go any eventual notes about this function...
|
||||
|
||||
@remarks ...here go any eventual remarks about this function...
|
||||
|
||||
@see ...here goes the see-also list...
|
||||
*/
|
||||
|
||||
Note that the @return, @note, @remarks, @see commands are optional.
|
||||
|
||||
The @param command has an optional attribute specifying the direction of
|
||||
the attribute. Possible values are "in" and "out". E.g.
|
||||
|
||||
/**
|
||||
* Copies bytes from a source memory area to a destination memory area,
|
||||
* where both areas may not overlap.
|
||||
* @param[out] dest The memory area to copy to.
|
||||
* @param[in] src The memory area to copy from.
|
||||
* @param[in] n The number of bytes to copy.
|
||||
* @param[in,out] pmisc Used both as input and as output.
|
||||
*/
|
||||
void func(void *dest, const void *src, size_t n, void *pmisc);
|
||||
|
||||
|
||||
Documentation comment for a topic overview
|
||||
==========================================
|
||||
|
||||
Topic overviews are stored inside the docs/doxygen/overviews folder
|
||||
and are completely placed inside a single comment block in the form of:
|
||||
|
||||
/*!
|
||||
|
||||
@page overview_tname wxSomeStuff overview
|
||||
|
||||
This page provides an overview of the wxSomeStuff and related classes.
|
||||
....
|
||||
|
||||
@li @ref overview_tname_intro
|
||||
@li @ref overview_tname_details
|
||||
...
|
||||
|
||||
<hr>
|
||||
|
||||
|
||||
@section overview_tname_intro Introduction
|
||||
|
||||
...here goes the introduction to this topic...
|
||||
|
||||
|
||||
@section overview_tname_details Details
|
||||
|
||||
...here go the details to this topic...
|
||||
|
||||
*/
|
||||
|
||||
Note that there is a convention in the anchor link names.
|
||||
Doxygen in fact requires that for each @page, @section, @subsection, etc tag,
|
||||
there is a corresponding link anchor.
|
||||
|
||||
The following conventions are used in wxWidgets doxygen comments:
|
||||
|
||||
1) all "main" pages of the manual (those which are placed in
|
||||
docs/doxygen/mainpages) have link anchors which begin with "page_"
|
||||
|
||||
2) all topic overviews (those which are placed in docs/doxygen/overviews) have
|
||||
link anchors which begin with "overview_"
|
||||
|
||||
3) all @section, @subsection, @subsubsection tags should have as link anchor
|
||||
name the name of the parent section plus a specific word separated with an
|
||||
underscore; e.g.:
|
||||
|
||||
/*!
|
||||
|
||||
@page overview_tname wxSomeStuff overview
|
||||
|
||||
@section overview_tname_intro Introduction
|
||||
@subsection overview_tname_intro_firstpart First part
|
||||
@subsection overview_tname_intro_secondpart Second part
|
||||
@subsubsection overview_tname_intro_secondpart_sub Second part subsection
|
||||
@subsection overview_tname_intro_thirdpart Third part
|
||||
|
||||
@section overview_tname_details Details
|
||||
...
|
||||
|
||||
*/
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: FM (along the lines of the previous technote about tex2rtf)
|
||||
Please see index.txt
|
||||
|
||||
@ -1,29 +0,0 @@
|
||||
Adding a wxWidgets contribution
|
||||
===============================
|
||||
|
||||
Here are some different kinds of contribution:
|
||||
|
||||
1. Bug fixes. You can send these to the wx-dev list.
|
||||
|
||||
2. New classes. They should go somewhere in the wxWidgets
|
||||
hierarchy if they are deemed to be 'core', otherwise they
|
||||
could be placed in external repositories of wxWidgets
|
||||
utilities, like wxCode (see http://wxcode.sf.net).
|
||||
|
||||
3. A utility application, such as a new dialog editor or
|
||||
file format conversion utility. If adding to the SVN
|
||||
archive, you may put it under the utils hierarchy,
|
||||
preferably with further src and docs directories.
|
||||
|
||||
You may or may not wish to add your code to the main wxWidgets SVN
|
||||
archive. Whether your code is appropriate for this archive
|
||||
should first be ascertained by discussing it on wx-dev@wxwidgets.org.
|
||||
|
||||
Also, in order to be included in wxWidgets, your code should
|
||||
follow the wxWidgets coding conventions
|
||||
(see http://www.wxwidgets.org/develop/standard.htm) and fit in the
|
||||
wxWidgets src, include, docs directories hierarchy.
|
||||
|
||||
|
||||
Author: Julian Smart
|
||||
|
||||
@ -1,59 +0,0 @@
|
||||
<HTML>
|
||||
|
||||
<HEAD>
|
||||
<TITLE>Creating and converting icons</TITLE>
|
||||
</HEAD>
|
||||
|
||||
<BODY BGCOLOR=#FFFFFF TEXT=#000000 LINK=#FF0000 VLINK=#000000>
|
||||
|
||||
<font face="Arial, Lucida Sans, Helvetica">
|
||||
|
||||
<a name="top"></a>
|
||||
|
||||
<table align=center width=100% border=4 cellpadding=5 cellspacing=0>
|
||||
<tr>
|
||||
<td bgcolor="#660000" align=left colspan=2>
|
||||
<font size=+1 face="Arial, Lucida Sans, Helvetica" color="#FFFFFF">
|
||||
Creating and converting icons
|
||||
</font>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<P>
|
||||
|
||||
Icons are bitmaps that may contain transparency information. Under X, icons are
|
||||
usually created from XPM files, which may be loaded from a file or created from
|
||||
data embedded in a C++ source file.<P>
|
||||
|
||||
Under Windows, icon files (extension .ico) may contain multiple icons for different sizes and colour
|
||||
depths, and can be loaded from a file or loaded from the Windows resources compiled
|
||||
into the executable.<P>
|
||||
|
||||
You can decide to use only XPMs on Windows and Unix, or you could use XPMs on Unix and
|
||||
Windows icons under Windows -- the latter will require some #ifdefs in your code or use of the wxICON macro.<P>
|
||||
|
||||
If you are using a compiler such as Borland C++ or Visual C++ you
|
||||
can use the provided icon editor. However, if using Cygwin or Mingw32, there
|
||||
is no icon editor so you must obtain one separately, such as <a href="http://hotfiles.zdnet.com/cgi-bin/texis/swlib/hotfiles/info.html?fcode=00165P">IconEdit32</a>.<P>
|
||||
|
||||
To convert from XPM to BMP (which can be loaded or pasted into an icon editor to save as an ICO file),
|
||||
you can use Vadim Zeitlin's <a href="ftp://biolpc22.york.ac.uk/pub/support/xpm2bmp.exe">xpm2bmp.exe</a> utility.
|
||||
To convert from BMP to XPM, you can use <a href="ftp://biolpc22.york.ac.uk/pub/support/bmp2xpm.exe">bmp2xpm.exe</a>
|
||||
which is actually the old wxWidgets 1.68 utility, xpmshow. You will have to edit the resulting
|
||||
file since the full path is used as the variable name, plus you may wish to specify a transparent colour e.g.:<P>
|
||||
|
||||
<pre>
|
||||
" s None c None",
|
||||
</pre>
|
||||
|
||||
This will indicate that the space character will be taken as the transparent colour throughout the image.<P>
|
||||
|
||||
<!--
|
||||
Author: JS
|
||||
-->
|
||||
|
||||
</font>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@ -1,51 +1 @@
|
||||
All about wxWidgets Version Numbers
|
||||
===================================
|
||||
|
||||
1. Where to update the version numbers:
|
||||
|
||||
There are several places in the wxWidgets source tree that
|
||||
define the version number for the library.
|
||||
|
||||
The script misc/scripts/inc_release can be used for incrementing the release
|
||||
field of the version, i.e. changing 2.8.x to 2.8.x+1 but it does not take
|
||||
care of version.bkl and can't be used for changing the other version
|
||||
components, this needs to be done manually. It also doesn't update
|
||||
version.bkl file which always needs to be updated manually, follow the
|
||||
instructions there.
|
||||
|
||||
Here is the list of files that need to be updated:
|
||||
|
||||
build/bakefiles/version.bkl {C:R:A} [NOT UPDATED AUTOMATICALLY]
|
||||
build/bakefiles/wxpresets/presets/wx.bkl [NOT UPDATED AUTOMATICALLY]
|
||||
configure.in
|
||||
build/osx/wxvers.xcconfig
|
||||
docs/changes.txt
|
||||
docs/readme.txt (date needs manual editing) [NOT UPDATED AUTOMATICALLY]
|
||||
docs/doxygen/Doxyfile (PROJECT_NUMBER and DOCSET_FEEDNAME)
|
||||
docs/doxygen/latexdocstart.inc
|
||||
docs/doxygen/mainpages/manual.h (just date) [NOT UPDATED AUTOMATICALLY]
|
||||
docs/msw/install.txt {major release only}
|
||||
include/wx/version.h
|
||||
include/wx/osx/config_xcode.h
|
||||
samples/Info.plist
|
||||
samples/docview/Info.plist
|
||||
samples/minimal/Info_carbon.plist
|
||||
samples/minimal/Info_cocoa.plist
|
||||
samples/minimal/borland_ide.cpp {major release only}
|
||||
|
||||
Do not forget to rebake everything after updating version.bkl!
|
||||
|
||||
2. When to update the version numbers:
|
||||
|
||||
Version should be updated immediately after releasing the previous version
|
||||
so that the sources in the repository always correspond to the next release
|
||||
and not the past one.
|
||||
|
||||
See also tn0020.txt.
|
||||
|
||||
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
|
||||
Please see index.txt
|
||||
|
||||
@ -1,122 +1 @@
|
||||
wxWidgets naming conventions
|
||||
============================
|
||||
|
||||
Being a cross platform development library, it is naturally desirable
|
||||
(at least to me ;) for wxWidgets to be exploited in a fully cross
|
||||
platform development environment -- a single invocation of make should
|
||||
be sufficient to build target executables for a variety of host platforms
|
||||
when desired.
|
||||
|
||||
Since this is now in fact possible for at least the most commonly used
|
||||
platforms, wxWidgets has been structured to allow multiple, simultaneous
|
||||
installations of the library. Common files are shared, platform and port
|
||||
specific files and libraries are arranged so as to be unambiguous when
|
||||
installed together.
|
||||
|
||||
To manage this sanely we need a sufficiently descriptive and logical
|
||||
labelling convention for file and install path names -- this document (at
|
||||
least at its time of writing) describes the system we have adopted.
|
||||
|
||||
It is not fine grained enough to include every possible build configuration
|
||||
for wxWidgets, but is encompassing enough to maintain a relatively complete
|
||||
set of cross platform build tools on a single machine and to provide an
|
||||
obvious slot for new ports to slip into.
|
||||
|
||||
|
||||
For UNIX libraries, the canonical library name shall be of the form:
|
||||
|
||||
libwx_$(toolkit)$(widgetset)$(debug)-$(version)-$(host).$(lib_extension)
|
||||
|
||||
For MSW (native hosted only) libraries the library name should be of
|
||||
the form:
|
||||
|
||||
wx$(toolkit)$(widgetset)$(version)$(unicode)$(debug).$(lib_extension)
|
||||
|
||||
|
||||
Where:
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$toolkit must currently be one of the following:
|
||||
|
||||
msw
|
||||
gtk
|
||||
base
|
||||
mac
|
||||
motif
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$widgetset may be one of:
|
||||
|
||||
univ
|
||||
|
||||
or empty if the widget set is the same as the toolkit.
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$version is a string encoding the full version (major, minor, release)
|
||||
for MSW, or just the major and minor number for UNIX.
|
||||
|
||||
eg. for wxWidgets 2.3.2, $version = 232 for MSW or 2.3 for UNIX.
|
||||
|
||||
The rationale for this is that under UNIX-like systems it is desirable
|
||||
that differently 'minor numbered' releases can be installed together,
|
||||
meaning your old 2.2 apps can continue to work even if you migrate
|
||||
development to the next stable or unstable release (eg. 2.3, 2.4),
|
||||
but binary compatibility is maintained between point releases (those
|
||||
with the same major.minor number)
|
||||
|
||||
A known break in binary compatibility should be addressed by updating
|
||||
the library soname (see the notes in configure.in for details on this)
|
||||
|
||||
I do not know why MSW should not also omit the release number from
|
||||
$version. (maybe that will change by the time this document is ratified)
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$unicode and $debug are either empty or set to 'u' and 'd'
|
||||
respectively when enabled.
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$host is empty for a 'native' library, (that is one where the host
|
||||
system is the same as the build system) or set to the value returned
|
||||
by the autoconf ${host_alias} variable in configure for libraries
|
||||
that are cross compiled.
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
$lib_extension is system specific and most usually set to .a for
|
||||
a static library, .dll for a MSW shared library, or .so.$so_version
|
||||
for a shared UNIX library.
|
||||
|
||||
====================================================================
|
||||
|
||||
|
||||
The installed location of the library specific setup.h is also
|
||||
determined by the values of these items. On UNIX systems they
|
||||
will be found in:
|
||||
|
||||
$(prefix)/lib/wx/include/$(toolkit)$(widgetset)$(debug)-$(version)-$(host)/wx/
|
||||
|
||||
which will be in the include search path returned by the relevant
|
||||
wx-config for that library. (or presumably set in the relevant
|
||||
make/project files for platforms that do not use wx-config)
|
||||
|
||||
====================================================================
|
||||
|
||||
|
||||
The port specific wx-config file for each library shall be named:
|
||||
|
||||
wx-$(toolkit)$(widgetset)$(debug)-$(version)-$(host)-config
|
||||
|
||||
${prefix}/bin/wx-config shall exist as a link to (or copy of) one of
|
||||
these port specific files (on platforms which support it) and as such
|
||||
it defines the default build configuration for wxApps on the system.
|
||||
It may be modified by the system user at any time.
|
||||
|
||||
|
||||
|
||||
---==O==---
|
||||
|
||||
Please see index.txt
|
||||
|
||||
@ -1,120 +1 @@
|
||||
How to add new bitmaps to wxWidgets UI elements
|
||||
===============================================
|
||||
|
||||
0. Introduction
|
||||
---------------
|
||||
|
||||
Since the introduction of wxArtProvider class, it is no longer desired to
|
||||
hardcode art resources (e.g. icons and toolbar or button bitmaps) into the
|
||||
code. This was previously done either by including the bitmap in win32
|
||||
resource file (include/wx/msw/wx.rc) or by including XPM files in the code.
|
||||
|
||||
wxArtProvider should be used instead, to allow users to customize the look of
|
||||
their wxWidgets app. This technote is a detailed description of steps needed
|
||||
when adding new bitmap/icon.
|
||||
|
||||
1. Adding new resource
|
||||
----------------------
|
||||
|
||||
(Please see wxArtProvider reference documentation for explanation of "art ID"
|
||||
and "art client" terms.)
|
||||
|
||||
First of all, you have to add new wxArtID constant to include/wx/artprov.h.
|
||||
Look for "Art IDs" and add new definition to the list, e.g.
|
||||
#define wxART_MY_BITMAP wxART_MAKE_ART_ID(wxART_MY_BITMAP)
|
||||
|
||||
Add it to interface/wx/artprov.h, too.
|
||||
|
||||
It may happen that the intended use of the new resource doesn't fit into any
|
||||
of defined client categories (search for "Art clients" in the header). In case
|
||||
the new resource is part of a larger category, you need to define a new
|
||||
client. Just add it to the list of existing clients (and don't forget to
|
||||
update artprov.tex):
|
||||
#define wxART_MY_CLIENT wxART_MAKE_CLIENT_ID(wxART_MY_CLIENT)
|
||||
|
||||
Alternatively, you may use wxART_OTHER when accessing the resource if the
|
||||
bitmap is standalone.
|
||||
|
||||
Once the header is updated, it's time to add XPM file with the bitmap to
|
||||
$(wx)/art. Add it to $(wx)/art if it is platform-independent or to
|
||||
$(wx)/art/$(toolkit) if it is something specific to one of the toolkits. Note
|
||||
that "specific to one of the toolkits" doesn't mean that the bitmap is *used*
|
||||
by only one toolkit, but that it doesn't make sense for any of the others! For
|
||||
example, a GTK wxART_WARNING icon ($(wx)/art/gtk/warning.xpm) is specific to
|
||||
wxGTK, but new_dir.xpm makes sense even under wxMSW even though it is
|
||||
currently only used by the generic file dialog. Remember that wxArtProvider
|
||||
can be used by users, not only the library.
|
||||
|
||||
Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated.
|
||||
This consists of two steps:
|
||||
|
||||
a) add #include line for your XPM file, e.g. #include "../../art/my_bmp.xpm"
|
||||
b) add ART(...) line to wxDefaultArtProvider::CreateBitmap(). The first
|
||||
argument is wxArtID, the other is XPM file name (w/o extension), e.g.
|
||||
ART(wxART_MY_BITMAP, my_bmp)
|
||||
|
||||
That's all. The bitmap is now available to wxArtProvider users.
|
||||
|
||||
Note: there's no difference between icons and bitmaps, always treat them as
|
||||
bitmaps inside wx(Default)ArtProvider.
|
||||
|
||||
1b. Adding Tango version of the resource.
|
||||
-----------------------------------------
|
||||
|
||||
While all the bitmaps are provided in XPM format so that they are available in
|
||||
all builds of wxWidgets, we also provide most of them in PNG format with full
|
||||
transparency support that is not available in XPM. Another advantage of the PNG
|
||||
versions is that the icons used are those of the Tango project and so have the
|
||||
consistent look, unlike the XPM ones.
|
||||
|
||||
So if you an icon exists in http://tango.freedesktop.org/Tango_Icon_Gallery you
|
||||
should add it too. For this you need to:
|
||||
|
||||
1. Convert the PNG to a C array of bytes suitable for inclusion in the code.
|
||||
This is done using misc/scripts/png2c.py script, e.g. if the variable "f"
|
||||
contains the name of the icon you want to add and you have installed Tango
|
||||
icons in a standard location under a Linux system:
|
||||
|
||||
./misc/scripts/png2c.py -s /usr/share/icons/Tango/{16x16,24x24}/*/$f.png >
|
||||
art/tango/${f//-/_}.h
|
||||
|
||||
Of course, the same command may be ran with different paths under Windows.
|
||||
Just remember to add both 16 and 24 pixel versions of the bitmap to the
|
||||
header and use the "-s" option to embed the image size in its array name.
|
||||
|
||||
2. Add #include for the newly created file to src/common/arttango.cpp.
|
||||
|
||||
3. Add an entry to s_allBitmaps array in the same file.
|
||||
|
||||
|
||||
2. Accessing the resource
|
||||
-------------------------
|
||||
|
||||
The file that will use the bitmap needs to include "wx/artprov.h". The code to
|
||||
access the bitmap (or icon) is trivial:
|
||||
|
||||
wxBitmap bmp = wxArtProvider::GetBitmap(wxART_MY_BITMAP, wxART_MY_CLIENT);
|
||||
// this would be "wxBitmap bmp(my_bmp_xpm);" before
|
||||
wxIcon icon = wxArtProvider::GetIcon(wxART_MY_ICON, wxART_MY_CLIENT);
|
||||
|
||||
Substitute wxART_MY_CLIENT in the example with a suitable client ID. If the
|
||||
client is wxART_OTHER you may write only
|
||||
|
||||
wxArtProvider::GetBitmap(wxART_MY_BITMAP).
|
||||
|
||||
3. Providing a demo
|
||||
-------------------
|
||||
|
||||
It is highly desirable to let the users know what stock bitmaps are available
|
||||
in wxWidgets. The "artprov" sample serves this purpose: it contains a browser
|
||||
dialog that displays all available art resources.
|
||||
|
||||
It has to be updated to accommodate for new bitmaps. Fortunately, this is
|
||||
trivial: open $(wx)/samples/artprov/artbrows.cpp in text editor and
|
||||
ART_ICON(wxART_MY_BITMAP) line to the FillBitmaps() function.
|
||||
|
||||
Similarly, if you add a new client, please update FillClients() by adding new
|
||||
client to the end of the list.
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Please see index.txt
|
||||
|
||||
@ -1,227 +1 @@
|
||||
How to add new files and libraries to wxWidgets build system
|
||||
============================================================
|
||||
|
||||
|
||||
1. 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.2 installed on Unix and either use Bakefile installer or have
|
||||
Python on Windows.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
You can use Bakefile to generate makefiles or projects customized to your
|
||||
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:
|
||||
bakefile -v -fmsvc6prj -o../wxmy.dsw -DRUNTIME_LIBS=dynamic
|
||||
-DDEBUG_INFO=default -DDEBUG_FLAG=default
|
||||
-DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1
|
||||
-DMONOLITHIC=0 -DUSE_GUI=1 -DWXUNIV=0 wx.bkl
|
||||
Or monolithic instead of multilib (the default):
|
||||
bakefile -v -fmsvc6prj -o../wxmono.dsw -DRUNTIME_LIBS=dynamic
|
||||
-DDEBUG_INFO=default -DDEBUG_FLAG=default
|
||||
-DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1
|
||||
-DMONOLITHIC=1 -DUSE_GUI=1 wx.bkl
|
||||
Or monolithic wxBase:
|
||||
bakefile -v -fmsvc6prj -o../wxBase.dsw -DRUNTIME_LIBS=dynamic
|
||||
-DDEBUG_INFO=default -DDEBUG_FLAG=default
|
||||
-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 <add-flags> and <del-flags> directives
|
||||
and use bakefile_gen instead of running bakefile directly.
|
||||
|
||||
|
||||
2. Bakefile files organization
|
||||
------------------------------
|
||||
|
||||
Makefile are generated from .bkl files ("bakefiles") from two places:
|
||||
- $(wx)/build/bakefiles directory
|
||||
- samples directories
|
||||
$(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
|
||||
|
||||
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
|
||||
|
||||
|
||||
3. 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.
|
||||
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
sources on all platforms (e.g. wxXml or wxXML) -- simply add the file to e.g.
|
||||
HTML_SRC or HTML_HDR.
|
||||
|
||||
If the file is used only on one platform and is part of wxBase, add it to
|
||||
BASE_{platform}_SRC/HDR. If it is used on all platforms, add it to BASE_CMN.
|
||||
If it is built on more than one platform but not on all of them, add the file
|
||||
to *all platforms that use it*!
|
||||
|
||||
If a file is not wxBase file, but GUI file, then the variables are named after
|
||||
toolkits/ports, not platforms. Same rules as for wxBase files apply
|
||||
(substitute "platform" with "toolkit"). Make sure you correctly choose between
|
||||
{port}_LOWLEVEL_SRC and {port}_SRC -- the former is for files used by
|
||||
wxUniversal, e.g. GDI classes. Files shared by all X Window System ports
|
||||
should be put into XWIN_LOWLEVEL_SRC.
|
||||
|
||||
|
||||
4. 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 <wx-data> node
|
||||
in the sample's bakefile (see e.g. samples/image/image.bkl for an example).
|
||||
Make sure to add <wx-lib> statements for all libraries from multilib build
|
||||
that are required by the sample.
|
||||
|
||||
The Windows resource specification should use the central .rc file:
|
||||
|
||||
<win32-res>../sample.rc</win32-res>
|
||||
|
||||
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 the generated makefiles except .dms, .vcp.
|
||||
|
||||
|
||||
5. Adding new core library
|
||||
--------------------------
|
||||
|
||||
When adding new library to the core set of libraries, the files must be
|
||||
added to both a newly added library in multilib build and into the single
|
||||
library built in monolithic mode. We will assume that the new library is
|
||||
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.
|
||||
* 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.
|
||||
* 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).
|
||||
* 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.
|
||||
|
||||
(You can apply different approaches to HDR and SRC variables, if e.g.
|
||||
headers are all common but sources are not.)
|
||||
|
||||
Note that the conditions can only test for equality, due to limitations of
|
||||
native make tools.
|
||||
|
||||
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.
|
||||
* 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:
|
||||
<set var="WXLIB_FOO">
|
||||
<if cond="MONOLITHIC=='0'">$(mk.evalExpr(wxwin.mkLibName('foo')))</if>
|
||||
</set>
|
||||
|
||||
c) Modify monolithic.bkl to add files to monolithic build: it's enough to add
|
||||
FOO_SRC to MONOLIB_GUI_SRC or MONOLIB_SRC, depending on whether wxFoo uses
|
||||
GUI or not.
|
||||
|
||||
d) Modify multilib.bkl to add files to multilib build: add foolib and foodll
|
||||
targets. Don't use wxBase targets as the template, use e.g. wxXML or wxHTML.
|
||||
Make sure WXMAKINGDLL_FOO is defined in foodll.
|
||||
|
||||
e) Regenerate all makefiles (don't forget to run autoconf)
|
||||
|
||||
f) Update configure.in and wx-config.in to contain information about
|
||||
the library and needed linker flags:
|
||||
* Add "foo" to BUILT_WX_LIBS in configure.in.
|
||||
* If appropriate, but it rarely is, so normally this should _not_ be done,
|
||||
add "foo" to either STD_BASE_LIBS or STD_GUI_LIBS in configure.in.
|
||||
* If wxFoo links against additional libraries, add necessary linker
|
||||
flags and libraries to ldflags_foo and ldlibs_foo variables in
|
||||
wx-config.in (both are optional).
|
||||
|
||||
g) Update dlimpexp.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add
|
||||
#define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in
|
||||
dlimpexp.h) and to define WXDLLIMPEXP_FOO and WXDLLIMPEXP_DATA_FOO. You
|
||||
can copy e.g. WXDLLIMPEXP_NET definition, it is something like this:
|
||||
#ifdef WXMAKINGDLL_NET
|
||||
#define WXDLLIMPEXP_NET WXEXPORT
|
||||
#define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type
|
||||
#elif defined(WXUSINGDLL)
|
||||
#define WXDLLIMPEXP_NET WXIMPORT
|
||||
#define WXDLLIMPEXP_DATA_NET(type) WXIMPORT type
|
||||
#else // not making nor using DLL
|
||||
#define WXDLLIMPEXP_NET
|
||||
#define WXDLLIMPEXP_DATA_NET(type) type
|
||||
#endif
|
||||
Don't forget to add WXDLLIMPEXP_FWD_FOO definitions too.
|
||||
Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions.
|
||||
|
||||
h) Add this code to one of wxFoo's files (the more often used, the better):
|
||||
// DLL options compatibility check:
|
||||
#include "wx/app.h"
|
||||
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)
|
||||
to show the dependencies of the new library.
|
||||
|
||||
j) Also please add 4 #pragma comment(lib, "foo") (for Unicode/ANSI
|
||||
Release/Debug 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.
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Please see index.txt
|
||||
|
||||
@ -1,144 +1 @@
|
||||
How to write unit tests for wxWidgets
|
||||
=====================================
|
||||
|
||||
Unit tests for wxWidgets are written using small cppunit framework. To compile
|
||||
(but not to run) them you need to have it installed. Hence the first part of
|
||||
this note explains how to do it while the second one explains how to write the
|
||||
test.
|
||||
|
||||
I. CppUnit Installation
|
||||
-----------------------
|
||||
|
||||
1. Get it from http://www.sourceforge.net/projects/cppunit
|
||||
(latest version as of the time of this writing is 1.10.2)
|
||||
|
||||
2. Build the library:
|
||||
a) Under Windows using VC++:
|
||||
- build everything in CppUnitLibraries.dsw work space
|
||||
- add include and lib subdirectories of the directory
|
||||
where you installed cppunit to the compiler search path
|
||||
using "Tools|Options" menu in VC IDE
|
||||
|
||||
b) Under Unix: run configure && make && make install as usual
|
||||
|
||||
|
||||
II. Writing tests with CppUnit
|
||||
------------------------------
|
||||
|
||||
1. Create a new directory tests/foo
|
||||
|
||||
2. Write a cpp file for the test copying, if you want,
|
||||
from one of the existing tests. The things to look for:
|
||||
a) #include "wx/cppunit.h" instead of directly including CppUnit headers
|
||||
b) don't put too many things in one test case nor in one method of a test
|
||||
case as it makes understanding what exactly failed harder later
|
||||
c) 'register' your tests as follows so that the test program will find and
|
||||
execute them:
|
||||
|
||||
// register in the unnamed registry so that these tests are run by default
|
||||
CPPUNIT_TEST_SUITE_REGISTRATION(MBConvTestCase);
|
||||
|
||||
// also include in its own registry so that these tests can be run alone
|
||||
CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(MBConvTestCase, "MBConvTestCase");
|
||||
|
||||
Read CppUnit documentation for more.
|
||||
d) wxUIActionSimulator can be used when user input is required, for example
|
||||
clicking buttons or typing text. A simple example of this can be found
|
||||
in controls/buttontest.cpp. After simulating some user input always
|
||||
wxYield to allow event processing. When writing a test using
|
||||
wxUIActionSimulator always add the test using WXUISIM_TEST rather than
|
||||
CPPUNIT_TEST as then it won't run on unsupported platforms. The test itself
|
||||
must also be wrapped in a #if wxUSE_UIACTIONSIMULATOR block.
|
||||
e) There are a number of classes that are available to help with testing GUI
|
||||
elements. Firstly throughout the test run there is a frame of type
|
||||
wxTestableFrame that you can access through wxTheApp->GetTopWindow(). This
|
||||
class adds two new functions, GetEventCount, which takes an optional
|
||||
wxEventType. It then returns the number of events of that type that it has
|
||||
received since the last call. Passing nothing returns the total number of
|
||||
event received since the last call. Also there is OnEvent, which counts the
|
||||
events based on type that are passed to it. To make it easy to count events
|
||||
there is also a new class called EventCounter which takes a window and event
|
||||
type and connects the window to the top level wxTestableFrame with the specific
|
||||
event type. It disconnects again once it is out of scope. It simply reduces
|
||||
the amount of typing required to count events.
|
||||
|
||||
3. add a '<sources>' tag for your source file to tests/test.bkl. Make sure it's
|
||||
in the correct section: the one starting '<exe id="test_gui"' for a gui test,
|
||||
the one starting '<exe id="test" template="wx_sample_console' otherwise.
|
||||
|
||||
|
||||
III. Running the tests
|
||||
----------------------
|
||||
|
||||
1. Regenerate the make/project files from test.bkl using bakefile_gen, e.g.:
|
||||
cd build/bakefiles
|
||||
bakefile_gen -b ../../tests/test.bkl
|
||||
and if you're on a unix system re-run configure.
|
||||
|
||||
2. Build the test program using one of the make/project files in the tests
|
||||
subdirectory.
|
||||
|
||||
3. Run the test program by using the command 'test' for the console tests,
|
||||
'test_gui' for the gui ones. With no arguments, all the default set of tests
|
||||
(all those registered with CPPUNIT_TEST_SUITE_REGISTRATION) are run.
|
||||
Or to list the test suites without running them:
|
||||
test -l or test_gui -l
|
||||
|
||||
4. Tests that have been registered under a name using
|
||||
CPPUNIT_TEST_SUITE_NAMED_REGISTRATION can also be run separately. For
|
||||
example:
|
||||
test_gui ButtonTestCase
|
||||
or to list the tests done by a particular testcase:
|
||||
test -L MBConvTestCase
|
||||
|
||||
5. Fault navigation.
|
||||
VC++ users can run the programs as a post build step (Projects/Settings/
|
||||
Post-build step) to see the test results in an IDE window. This allows
|
||||
errors to be jumped to in the same way as for compiler errors, for
|
||||
example by pressing F4 or highlighting the error and pressing return.
|
||||
|
||||
Similarly for makefile users: makefiles can be modified to execute the
|
||||
test programs as a final step. Then you can navigate to any errors in the
|
||||
same way as for compiler errors, if your editor supports that.
|
||||
|
||||
Another alternative is to run the tests manually, redirecting the output
|
||||
to a file. Then use your editor to jump to any failures. Using Vim, for
|
||||
example, ':cf test.log' would take you to the first error in test.log, and
|
||||
':cn' to the next.
|
||||
|
||||
If you would like to set a breakpoint on a failing test using a debugger,
|
||||
put the breakpoint on the function 'CppUnit::Asserter::fail()'. This will
|
||||
stop on each failing test.
|
||||
|
||||
|
||||
IV. Notes
|
||||
---------
|
||||
|
||||
1. You can register your tests (or a subset of them) just under a name, and not
|
||||
in the unnamed registry if you don't want them to be executed by default.
|
||||
|
||||
2. If you are going to register your tests both in the unnamed registry
|
||||
and under a name, then use the name that the tests have in the 'test -l'
|
||||
listing.
|
||||
|
||||
3. Tests which fail can be temporarily registered under "fixme" while the
|
||||
problems they expose are fixed, instead of the unnamed registry. That
|
||||
way they can easily be run, but they do not make regression testing with
|
||||
the default suite more difficult. E.g.:
|
||||
|
||||
// register in the unnamed registry so that these tests are run by default
|
||||
//CPPUNIT_TEST_SUITE_REGISTRATION(wxRegExTestCase);
|
||||
CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "fixme");
|
||||
|
||||
// also include in its own registry so that these tests can be run alone
|
||||
CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "wxRegExTestCase");
|
||||
|
||||
4. Tests which take a long time to execute can be registered under "advanced"
|
||||
instead of the unnamed registry. The default suite should execute reasonably
|
||||
quickly. To run the default and advanced tests together:
|
||||
test "" advanced
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ & MW
|
||||
Please see index.txt
|
||||
|
||||
@ -1,67 +1 @@
|
||||
How to add a new font encoding to wxWidgets
|
||||
===========================================
|
||||
|
||||
I. Introduction
|
||||
---------------
|
||||
|
||||
wxWidgets has built in support for a certain number of font encodings (which
|
||||
is synonymous with code sets and character sets for us here even though it is
|
||||
not exactly the same thing), look at include/wx/fontenc.h for the full list.
|
||||
This list is far from being exhaustive though and if you have enough knowledge
|
||||
about an encoding to add support for it to wxWidgets, this tech note is for
|
||||
you!
|
||||
|
||||
A word of warning though: this is written out of my head and is surely
|
||||
incomplete. Please correct the text here, especially if you detect problems
|
||||
when you try following it.
|
||||
|
||||
Also note that I completely ignore all the difficult issues of support for
|
||||
non European languages in the GUI (i.e. BiDi and text orientation support).
|
||||
|
||||
|
||||
II. The receipt
|
||||
---------------
|
||||
|
||||
Suppose you want to add support for Klingon to wxWidgets. This is what you'd
|
||||
have to do:
|
||||
|
||||
1. include/wx/fontenc.h: add a new wxFONTENCODING_KLINGON enum element, if
|
||||
possible without changing the values of the existing elements of the enum
|
||||
and be careful to now make it equal to some other elements -- this means
|
||||
that you have to put it before wxFONTENCODING_MAX
|
||||
|
||||
2. wxFONTENCODING_MAX must be the same as the number of elements in 3
|
||||
(hopefully) self explanatory arrays in src/common/fmapbase.cpp:
|
||||
a) gs_encodings
|
||||
b) gs_encodingDescs
|
||||
c) gs_encodingNames
|
||||
|
||||
You must update all of them, e.g. you'd add wxFONTENCODING_KLINGON,
|
||||
"Klingon (Star Trek)" and "klingon" to them in this example. The latter
|
||||
name should ideally be understandable to both Win32 and iconv as it is used
|
||||
to convert to/from this encoding under Windows and Unix respectively.
|
||||
Typically any reasonable name will be supported by iconv, if unsure run
|
||||
"iconv -l" on your favourite Unix system. For the list of charsets
|
||||
supported under Win32, look under HKEY_CLASSES_ROOT\MIME\Database\Charset
|
||||
in regedit. Of course, being consistent with the existing encoding names
|
||||
wouldn't hurt neither.
|
||||
|
||||
3. Normally you don't have to do anything else if you've got support for this
|
||||
encoding under both Win32 and Unix. If you haven't, you should modify
|
||||
wxEncodingConverter to support it (this could be useful anyhow as a
|
||||
fallback for systems where iconv is unavailable). To do it you must:
|
||||
a) add a new table to src/common/unictabl.inc: note that this file is auto
|
||||
generated so you have to modify misc/unictabl script instead (probably)
|
||||
b) possibly update EquivalentEncodings table in src/common/encconv.cpp
|
||||
if wxFONTENCODING_KLINGON can be converted into another one
|
||||
(losslessly only or not?)
|
||||
|
||||
4. Add a unit test (see tn0017.txt) for support of your new encoding (with
|
||||
time we should have a wxCSConv unit test so you would just add a case to
|
||||
it for wxFONTENCODING_KLINGON) and test everything on as many different
|
||||
platforms as you can.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
Please see index.txt
|
||||
|
||||
@ -1,53 +1 @@
|
||||
Special notes about writing wxMSW code
|
||||
======================================
|
||||
|
||||
0. Purpose
|
||||
----------
|
||||
|
||||
This is just a collection of various notes which should be useful to anybody
|
||||
working on wxMSW codebase, please feel free to add more here.
|
||||
|
||||
This text assumes familiarity with both Windows programming and wxWidgets so it
|
||||
doesn't cover any wxWidgets-wide issues not specific to Windows.
|
||||
|
||||
|
||||
1. Windows headers wrappers
|
||||
---------------------------
|
||||
|
||||
In no event should the Windows headers such as <windows.h> or <commctrl.h> be
|
||||
included directly. So instead of #include <...> use "wx/msw/wrapwin.h" or
|
||||
"wx/msw/wrapcctl.h".
|
||||
|
||||
For convenience it is also possible to replace #include <commdlg.h> and
|
||||
<shlobj.h> with #include "wx/msw/wrapcdlg.h" and wrapshl.h but this is less
|
||||
vital.
|
||||
|
||||
Also notice that many convenient (albeit undocumented) functions and classes
|
||||
are declared in "wx/msw/private.h", please do become familiar with this file
|
||||
contents and use the utility classes and functions from it instead of
|
||||
duplicating their functionality (which can often be done only in exception
|
||||
unsafe way).
|
||||
|
||||
|
||||
2. Windows features checks
|
||||
--------------------------
|
||||
|
||||
All checks of features not present in all Windows versions must be done both at
|
||||
compile-time (because, even though we use maximal value for WINVER in our code,
|
||||
some compilers come with headers too old to declare them) and at run-time
|
||||
(because wxMSW applications should run everywhere).
|
||||
|
||||
The functions wxGetWinVersion() (from wx/msw/private.h) and wxApp::
|
||||
GetComCtl32Version() should be used to check Windows and comctl32.dll versions
|
||||
respectively.
|
||||
|
||||
Any functions which may not be present in kernel32.dll/user32.dll/... in all
|
||||
Windows versions should be resolved dynamically, i.e. using wxDynamicLibrary as
|
||||
otherwise any wx application -- even not needing them at all -- would refuse to
|
||||
start up on Windows versions not implementing the feature in question. As an
|
||||
example, look at AlphaBlt()-related code in src/msw/dc.cpp.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
Please see index.txt
|
||||
|
||||
@ -1,287 +1 @@
|
||||
Binary Compatibility and wxWidgets
|
||||
==================================
|
||||
0. Purpose
|
||||
----------
|
||||
|
||||
This is a broad technote covering all aspects of binary compatibility with
|
||||
wxWidgets.
|
||||
|
||||
1. Releases
|
||||
-----------
|
||||
|
||||
General overview of releases can be found in tn0012.txt, but for
|
||||
completeness the wxWidgets release version number is as follows:
|
||||
|
||||
2.6.2
|
||||
|
||||
Where
|
||||
|
||||
2 6 2
|
||||
Major Minor Release
|
||||
|
||||
(I.E. Major.Minor.Release).
|
||||
|
||||
All versions with EVEN minor version component (e.g. 2.4.x, 2.6.x etc.)
|
||||
are expected to be binary compatible (ODD minors are development versions
|
||||
and the compatibility constraints don't apply to them). Note that by
|
||||
preserving binary compatibility we mean BACKWARDS compatibility only,
|
||||
meaning that applications built with old wxWidgets headers should continue
|
||||
to work with new wxWidgets (shared/dynamic) libraries without the need to
|
||||
rebuild. There is no requirement to preserve compatibility in the other
|
||||
direction (i.e. make new headers compatible with old libraries) as this
|
||||
would preclude any additions whatsoever to the stable branch. But see
|
||||
also section (4).
|
||||
|
||||
|
||||
2. What kind of changes are NOT binary compatible
|
||||
-------------------------------------------------
|
||||
|
||||
If its still up, the KDE guide is a good reference:
|
||||
http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++
|
||||
|
||||
The changes that are NOT binary compatible:
|
||||
- Adding a virtual function
|
||||
- Changing the name of a any function or variable
|
||||
- Changing the signature of a virtual function (adding a parameter,
|
||||
even a default one)
|
||||
- Changing the order of the virtual functions in a class
|
||||
["switching" them, etc.]
|
||||
- Changing access privileges of a function: some compilers (among which MSVC)
|
||||
use the function access specifier in its mangled name. Moreover, while
|
||||
changing a private function to public should be compatible (as the old
|
||||
symbol can't be referenced from outside the library anyhow), changing a
|
||||
virtual private function to public is NOT compatible because the old symbol
|
||||
is referenced by the virtual tables in the executable code and so an old
|
||||
program compiled with MSVC wouldn't start up with a new DLL even if it
|
||||
doesn't use the affected symbol at all!
|
||||
- Adding a member variable
|
||||
- Changing the order of non-static member variables
|
||||
|
||||
|
||||
3. Changes which are compatible
|
||||
-------------------------------
|
||||
|
||||
- Adding a new class
|
||||
- Adding a new non-virtual method to an existing class
|
||||
- Adding a new constructor to an existing class
|
||||
- Overriding the implementation of an existing virtual function
|
||||
[this is considered to be backwards binary compatible until we find a
|
||||
counter example; currently it's known to work with Apple gcc at least]
|
||||
- Anything which doesn't result in ABI change at all, e.g. adding new
|
||||
macros, constants and, of course, private changes in the implementation
|
||||
|
||||
|
||||
4. wxABI_VERSION and "forward" binary compatibility
|
||||
--------------------------------------------------
|
||||
|
||||
As mentioned we do not support "forward" binary compatibility, that is the
|
||||
ability to run applications compiled with new wxWidgets headers on systems
|
||||
with old wxWidgets libraries.
|
||||
|
||||
However, for the developers who want to ensure that their application works
|
||||
with some fixed old wxWidgets version and doesn't (inadvertently) require
|
||||
features added in later releases, we provide the macro wxABI_VERSION which
|
||||
can be defined to restrict the API exported by wxWidgets headers to that of
|
||||
a fixed old release.
|
||||
|
||||
For this to work, all new symbols added to binary compatible releases must
|
||||
be #if'ed with wxABI_VERSION.
|
||||
|
||||
The layout of wxABI_VERSION is as follows:
|
||||
|
||||
20602
|
||||
|
||||
where
|
||||
|
||||
2 06 02
|
||||
Major Minor Release
|
||||
|
||||
I.E. it corresponds to the wxWidgets release in (1).
|
||||
|
||||
An example of using wxABI_VERSION is as follows for symbols
|
||||
only in a 2.6.2 release:
|
||||
|
||||
#if wxABI_VERSION >= 20602 /* 2.6.2+ only */
|
||||
bool Load(const wxURI& location, const wxURI& proxy);
|
||||
|
||||
wxFileOffset GetDownloadProgress();
|
||||
wxFileOffset GetDownloadTotal();
|
||||
|
||||
bool ShowPlayerControls(
|
||||
wxMediaCtrlPlayerControls flags =
|
||||
wxMEDIACTRLPLAYERCONTROLS_DEFAULT);
|
||||
|
||||
//helpers for the wxPython people
|
||||
bool LoadURI(const wxString& fileName)
|
||||
{ return Load(wxURI(fileName)); }
|
||||
bool LoadURIWithProxy(const wxString& fileName, const wxString& proxy)
|
||||
{ return Load(wxURI(fileName), wxURI(proxy)); }
|
||||
#endif
|
||||
|
||||
|
||||
5. Workarounds for adding virtual functions
|
||||
-------------------------------------------
|
||||
|
||||
Originally the idea for adding virtual functions to binary compatible
|
||||
releases was to pad out some empty "reserved" functions and then
|
||||
rename those later when someone needed to add a virtual function.
|
||||
|
||||
However, after there was some actual testing of the idea a lot of
|
||||
controversy erupted. Eventually we decided against the idea, and
|
||||
instead devised a new method for doing so called wxShadowObject.
|
||||
|
||||
wxShadowObject is a class derived from wxObject that provides a means
|
||||
of adding functions and/or member variables to a class internally
|
||||
to wxWidgets. It does so by storing these in a hash map inside of
|
||||
it, looking it up when the function etc. is called. wxShadowObject
|
||||
is generally stored inside a reserved member variable.
|
||||
|
||||
wxShadowObject resides in include/wx/clntdata.h.
|
||||
|
||||
To use wxShadowObject, you first call AddMethod or AddField with
|
||||
the first parameter being the name of the field and/or method
|
||||
you want, and the second parameter being the value of the
|
||||
field and/or method.
|
||||
|
||||
In the case of fields this is a void*, and in the case of method
|
||||
is a wxShadowObjectMethod which is a typedef:
|
||||
typedef int (*wxShadowObjectMethod)(void*, void*);
|
||||
|
||||
After you add a field, you can set it via SetField with the same
|
||||
parameters as AddField, the second parameter being the value to set
|
||||
the field to. You can get the field after you call AddField
|
||||
via GetField, with the parameters as the other two field functions,
|
||||
only in the case the second parameter is the fallback
|
||||
value for the field in the case of it not being found in the
|
||||
hash map.
|
||||
|
||||
You can call a method after you add it via InvokeMethod, which
|
||||
returns a bool indicating whether or not the method was found
|
||||
in the hash map, and has 4 parameters. The first parameter is
|
||||
the name of the method you wish to call, the second is the first
|
||||
parameter passed to the wxShadowObjectMethod, the third is the
|
||||
second parameter passed to that wxShadowObjectMethod, and the
|
||||
fourth is the return value of the wxShadowObjectMethod.
|
||||
|
||||
6. version-script.in
|
||||
--------------------
|
||||
|
||||
For ld/libtool we use sun-style version scripts. Basically
|
||||
anything which fits the conditions of being #if'ed via wxABI_VERSION
|
||||
needs to go here also.
|
||||
|
||||
See 'info ld scripts version' on a GNU system, it's online here:
|
||||
http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html
|
||||
|
||||
Or see chapter 5 of the 'Linker and Libraries Guide' for Solaris, available
|
||||
online here:
|
||||
http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWdev/LLM/p1.html
|
||||
|
||||
The file has the layout as follows:
|
||||
|
||||
@WX_VERSION_TAG@.X
|
||||
|
||||
Where X is the current Release as mentioned earlier, i.e. 2. This
|
||||
is following by an opening bracket "{", followed by "global:",
|
||||
followed by patterns matching added symbols, then followed by "}", and then
|
||||
the file is either followed by earlier Releases or ended by
|
||||
a @WX_VERSION_TAG@ block without the period or Release.
|
||||
|
||||
The patterns used to specify added symbols are globbing patters and can
|
||||
contain wildcards such as '*'.
|
||||
|
||||
For example for a new class member such as:
|
||||
wxFont wxGenericListCtrl::GetItemFont( long item ) const;
|
||||
|
||||
the mangled symbol might be:
|
||||
_ZNK17wxGenericListCtrl11GetItemFontEl
|
||||
|
||||
so a line like this could be added to version-script.in:
|
||||
*wxGenericListCtrl*GetItemFont*;
|
||||
|
||||
Allow for the fact that the name mangling is going to vary from compiler to
|
||||
complier.
|
||||
|
||||
When adding a class you can match all the symbols it adds with a single
|
||||
pattern, so long as that pattern is not likely to also match other symbols.
|
||||
For example for wxLogBuffer a line like this:
|
||||
*wxLogBuffer*;
|
||||
|
||||
|
||||
7. Checking the version information in libraries and programs
|
||||
-------------------------------------------------------------
|
||||
|
||||
On Sun there is a tool for this, see pvs(1). On GNU you can use objdump, below
|
||||
are some examples.
|
||||
|
||||
To see what versions of each library a program (or library) depends on:
|
||||
|
||||
$ objdump -p widgets | sed -ne '/Version References/,/^$/p'
|
||||
Version References:
|
||||
required from libgcc_s.so.1:
|
||||
0x0b792650 0x00 10 GCC_3.0
|
||||
required from libwx_based-2.6.so.0:
|
||||
0x0cca2546 0x00 07 WXD_2.6
|
||||
required from libstdc++.so.6:
|
||||
0x056bafd3 0x00 09 CXXABI_1.3
|
||||
0x08922974 0x00 06 GLIBCXX_3.4
|
||||
required from libwx_gtk2d_core-2.6.so.0:
|
||||
0x0a2545d2 0x00 08 WXD_2.6.2
|
||||
0x0cca2546 0x00 05 WXD_2.6
|
||||
required from libc.so.6:
|
||||
0x09691a75 0x00 04 GLIBC_2.2.5
|
||||
|
||||
To see what WXD_2.6.2 symbols a program uses:
|
||||
|
||||
$ objdump -T widgets | grep 'WXD_2\.6\.2'
|
||||
0000000000000000 g DO *ABS* 0000000000000000 WXD_2.6.2 WXD_2.6.2
|
||||
00000000004126d8 DF *UND* 0000000000000177 WXD_2.6.2 _ZN19wxTopLevelWindowGTK20RequestUserAttentionEi
|
||||
|
||||
To see what WXD_2.6.2 symbols a library defines:
|
||||
|
||||
$ objdump -T libwx_based-2.6.so | grep 'WXD_2\.6\.2' | grep -v 'UND\|ABS'
|
||||
0000000000259a10 w DO .data 0000000000000018 WXD_2.6.2 _ZTI19wxMessageOutputBest
|
||||
00000000002599e0 w DO .data 0000000000000028 WXD_2.6.2 _ZTV19wxMessageOutputBest
|
||||
000000000010a98e w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD0Ev
|
||||
0000000000114efb w DO .rodata 000000000000000e WXD_2.6.2 _ZTS11wxLogBuffer
|
||||
0000000000255590 w DO .data 0000000000000018 WXD_2.6.2 _ZTI11wxLogBuffer
|
||||
000000000011b550 w DO .rodata 0000000000000016 WXD_2.6.2 _ZTS19wxMessageOutputBest
|
||||
00000000000bfcc8 g DF .text 00000000000000dd WXD_2.6.2 _ZN11wxLogBuffer5DoLogEmPKcl
|
||||
000000000010a3a6 g DF .text 0000000000000153 WXD_2.6.2 _ZN19wxMessageOutputBest6PrintfEPKcz
|
||||
00000000000c0b22 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD0Ev
|
||||
00000000000bfc3e g DF .text 0000000000000089 WXD_2.6.2 _ZN11wxLogBuffer5FlushEv
|
||||
00000000000c0ad6 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD1Ev
|
||||
00000000000b1130 w DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBufferC1Ev
|
||||
00000000000c095c w DF .text 0000000000000029 WXD_2.6.2 _ZN19wxMessageOutputBestC1Ev
|
||||
00000000000c08e8 w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD1Ev
|
||||
00000000002554c0 w DO .data 0000000000000038 WXD_2.6.2 _ZTV11wxLogBuffer
|
||||
00000000000bfda6 g DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBuffer11DoLogStringEPKcl
|
||||
00000000000abe10 g DF .text 0000000000000088 WXD_2.6.2 _ZN14wxZipFSHandler7CleanupEv
|
||||
|
||||
|
||||
8. Testing binary compatibility between releases
|
||||
------------------------------------------------
|
||||
|
||||
An easy way of testing binary compatibility is just to build wxWidgets
|
||||
in dll/dynamic library mode and then switch out the current library
|
||||
in question with an earlier stable version of the library, then running
|
||||
the application in question again. If it runs OK then there is usually
|
||||
binary compatibility between those releases.
|
||||
|
||||
You can also break into your debugger or whatever program you want
|
||||
to use and check the memory layout of the class. If it is the same
|
||||
then it is binary compatible.
|
||||
(In GDB the command x/d will show addresses as pointers to functions if
|
||||
possible so you can see if the order of the functions in vtbl doesn't change.)
|
||||
|
||||
Another way to check for binary compatibility is to build wxWidgets in shared mode
|
||||
and use the 'abicheck.sh --generate' script before doing your changes to generate
|
||||
the current ABI (if the 'expected_abi' file is not already in the repo).
|
||||
Then rebuild wxWidgets with your changes and use 'abicheck.sh' to compare the
|
||||
resulting ABI with the expected one.
|
||||
Note that the abicheck.sh script is in the "lib" folder.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: RN
|
||||
Please see index.txt
|
||||
|
||||
@ -1,83 +1 @@
|
||||
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. Files to update
|
||||
------------------
|
||||
|
||||
The following files need to be modified when adding a new wxUSE_FOO:
|
||||
|
||||
a) 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).
|
||||
|
||||
a') include/wx/msw/setup_inc.h for MSW-specific options
|
||||
|
||||
This file contains MSW-specific options, so if the new option is only used
|
||||
under MSW, add it here instead of include/wx/setup_inc.h. The rest of the
|
||||
instructions is the same as above.
|
||||
|
||||
b) include/wx/chkconf.h
|
||||
|
||||
Add the check for wxUSE_FOO definedness in the corresponding (base or GUI)
|
||||
section. Please keep the alphabetic order.
|
||||
|
||||
If there are any dependencies, i.e. wxUSE_FOO requires wxUSE_BAR and
|
||||
wxUSE_BAZ, check for thme here too.
|
||||
|
||||
b') include/wx/msw/chkconf.h for MSW-specific options
|
||||
|
||||
These options won't be defined for the other ports, so shouldn't be added to
|
||||
the common include/wx/chkconf.h but to this file instead.
|
||||
|
||||
c) 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.
|
||||
|
||||
d) docs/doxygen/mainpages/const_wxusedef.h
|
||||
|
||||
Add a brief description of the new constant.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
|
||||
Please see index.txt
|
||||
|
||||
@ -1,180 +1 @@
|
||||
Making a new wxWidgets release
|
||||
==============================
|
||||
|
||||
Before making the release
|
||||
-------------------------
|
||||
|
||||
Change the version in include/wx/version.h.
|
||||
|
||||
Update docs/readme.txt. Please review its contents in addition to just
|
||||
changing the version number.
|
||||
|
||||
Put a date on the release line in docs/changes.txt.
|
||||
|
||||
Update the date in the manual (docs/doxygen/mainpages/manual.h).
|
||||
|
||||
Update the release announcement post in docs/publicity/announce.txt.
|
||||
|
||||
|
||||
Creating release files
|
||||
----------------------
|
||||
|
||||
The currently used release scripts need to be used from git-svn checkout and
|
||||
rely on Git to avoid problems with using non-clean trees and such. If you don't
|
||||
use Git you may use the alternative archive creation scripts in the next
|
||||
section.
|
||||
|
||||
Follow these steps assuming the current working directory is the root of git
|
||||
working copy and you want to prepare distribution for the version x.y.z:
|
||||
|
||||
1. Run "./build/tools/svn-find-native-eols.pl > ../eol-native" (if you have
|
||||
an existing svn checkout, pass it to the script to make it run much faster,
|
||||
but take care to have up to date sources in the working tree).
|
||||
|
||||
2. Run "./build/tools/git-make-release x.y.z" to create source archives
|
||||
../wxWidgets-x.y.z.{7z,tar.bz2,zip} and wxWidgets_x.y.z_Headers.zip.
|
||||
|
||||
3. Run "./build/tools/make-html-docs x.y.z" to create HTML documentation
|
||||
archives ../wxWidgets-x.y.z.{tar.bz2,zip}
|
||||
|
||||
4. This step must be done under Windows as it relies on having hhc.exe, the
|
||||
Html Help compiler, in PATH: run the following commands
|
||||
|
||||
cd docs\doxygen
|
||||
regen.bat chm
|
||||
cd out
|
||||
zip ..\..\..\wxWidgets-x.y.z-docs-chm.zip wx.chm
|
||||
|
||||
5. This step also must be done under Windows as it uses Inno Setup to produce
|
||||
the .exe file and it also requires the CHM file built above:
|
||||
|
||||
md x.y.z-sources
|
||||
cd x.y.z-sources
|
||||
7z x ..\wxWidgets-x.y.z.7z
|
||||
md docs\htmlhelp
|
||||
cp ..\docs\doxygen\out\wx.chm docs\htmlhelp
|
||||
set WXW_VER=x.y.z
|
||||
iscc build\tools\wxwidgets.iss
|
||||
|
||||
|
||||
|
||||
Instructions for the previous version of release scripts
|
||||
--------------------------------------------------------
|
||||
|
||||
NB: These scripts haven't been used since 2.8 series and may not work any longer!
|
||||
|
||||
Currently our release system uses a Python 2.x script to generate releases.
|
||||
The script requires Unix utilities such as tar, zip and unix2dos and thus must
|
||||
be run either on Unix or using Cygwin on Windows. To generate a release, simply
|
||||
run the following command:
|
||||
|
||||
build/tools/create-archive.py --compression=all /path/to/output/dir
|
||||
|
||||
This will produce zip, gzip and bzip archives of the tree (without
|
||||
"compression" argument only .gz is made). Note that this commands produces huge
|
||||
amounts of output so redirecting it to a file is recommended.
|
||||
|
||||
To add a prefix to the release, such as RC1, the SVN revision, or a date, just
|
||||
pass --postfix="postfix" to the script. More info on the options and their
|
||||
possible values can be found by calling `create-archive.py --help`.
|
||||
|
||||
IMPORTANT NOTE: You *must* run this script from a clean source tree, that is,
|
||||
with no junk files in it or modifications. This is because the
|
||||
release should be a pristine copy of the tree as of the time of
|
||||
release. If you have legitimate modifications in the tree that need
|
||||
to be in the release, commit them first.
|
||||
|
||||
To generate the windows installer (.exe) and the documentation files (chm and htb formats)
|
||||
run:
|
||||
|
||||
build\tools\bld_chm_exe.bat
|
||||
|
||||
which depends on the wxwidgets.iss file, and generates output in the %DAILY% directory. It
|
||||
assumes a clean copy of the wxWidgets source tree in %INNO%. Temporary files will be generated
|
||||
in the tree from which the batch file is run. It depends on doxygen, a number of gnu
|
||||
win32 tools and Microsofts htmlhelp compiler. The wxwidgets.iss file should not need
|
||||
editing, but you will want to check that the bld_chm_exe.bat has the correct version number.
|
||||
|
||||
|
||||
|
||||
Uploading
|
||||
---------
|
||||
|
||||
Upload the files to SourceForge. This can be done via the web interface or just
|
||||
scp to sfusername,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z
|
||||
The following files need to be uploaded:
|
||||
|
||||
wxMSW-Setup-x.y.z.exe
|
||||
wxWidgets-x.y.z.7z
|
||||
wxWidgets-x.y.z.tar.bz2
|
||||
wxWidgets-x.y.z.zip
|
||||
wxWidgets-docs-chm-x.y.z.zip
|
||||
wxWidgets-docs-html-x.y.z.tar.bz2
|
||||
wxWidgets-docs-html-x.y.z.zip
|
||||
|
||||
The file wxWidgets-x.y.z_Headers.7z should be uploaded to binaries
|
||||
subdirectory as it's only useful when using pre-built binaries.
|
||||
|
||||
You will need to use the web interface to mark the latest uploaded files as
|
||||
being "default downloads" for the appropriate platforms (.zip or .exe for MSW,
|
||||
.tar.bz2 for everything else) as otherwise SourceForge would continue to suggest
|
||||
people to download old files.
|
||||
|
||||
Next, update (at least the versions and SHA1 sums, but maybe more) and upload
|
||||
docs/release_files.mdwn and docs/release_binaries.mdwn files. They need to be
|
||||
renamed to README.md on SF to be shown when the directory is viewed, i.e. do:
|
||||
|
||||
scp docs/release_files.mdwn \
|
||||
sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z/README.md
|
||||
scp docs/release_binaries.mdwn \
|
||||
sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z/binaries/README.md
|
||||
|
||||
And upload the change log too:
|
||||
|
||||
scp docs/changes.txt \
|
||||
sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z
|
||||
|
||||
|
||||
Also upload the files to the FTP mirror at ftp.wxwidgets.org (ask Chris for
|
||||
access if you don't have it).
|
||||
|
||||
Create http://docs.wxwidgets.org/x.y.z/ (ask Bryan to do it if not done yet).
|
||||
|
||||
|
||||
Announcement
|
||||
------------
|
||||
|
||||
Post docs/publicity/announce.txt at least to wx-announce@googlegroups.com and
|
||||
to wx-users for the important releases.
|
||||
|
||||
Submit a link to http://www.reddit.com/r/programming
|
||||
|
||||
Submit to http://isocpp.org/blog/suggest
|
||||
|
||||
For major releases, submit the announcement to http://slashdot.org/submission
|
||||
|
||||
Update www.wxwidgets.org, usually a news item is enough but something more can
|
||||
be called for for major releases.
|
||||
|
||||
Modify the links at downloads/index.html to point to the new release.
|
||||
|
||||
Also update docs/index.html for the minor or major (i.e. not micro) releases.
|
||||
|
||||
Post to wxBlog if necessary.
|
||||
|
||||
Announce on Google+/Twitter/whatever the person doing the release prefers (we
|
||||
don't have "official" wxWidgets account, should we?).
|
||||
|
||||
|
||||
Version updates
|
||||
---------------
|
||||
|
||||
Trac: mark the milestone corresponding to the release as completed and add a
|
||||
new version for it to allow reporting bugs against it and create the next
|
||||
milestone (ask Vadim or Robin to do it or to get admin password).
|
||||
|
||||
Run misc/scripts/inc_release to increment micro version, i.e. replace x.y.z
|
||||
with x.y.z+1 (minor or major versions updates require manual intervention).
|
||||
|
||||
Update the definition of the stable and release branches in
|
||||
build/buildbot/config/include/defs.xml after a minor version change.
|
||||
Please see index.txt
|
||||
|
||||
@ -1,35 +0,0 @@
|
||||
Adding a new app/screenshot to the wxWidgets.org front page
|
||||
=====================================
|
||||
|
||||
To add a new app/screenshot to the front page, you first will need to have the
|
||||
following:
|
||||
|
||||
1. The application Name
|
||||
2. A URL for the application
|
||||
3. A series of screenshots for the app
|
||||
|
||||
Each screenshot should have a 300 pixel width. A height around 225 pixels is
|
||||
preferred, but it's more important to keep the aspect ratio of the screenshot.
|
||||
Screenshot format is not important, but the important thing is to use the format
|
||||
that gives you the best ratio of picture compression and size. Also, please
|
||||
make sure the screenshots all have the app name in them.
|
||||
|
||||
Once you have the screenshots and info ready, take the following steps to
|
||||
update the web site:
|
||||
|
||||
1) Put the screenshots in <wxWebSite root>/site-v2/images/front_screens
|
||||
|
||||
2) Open <wxWebSite root>/site-v2/index.php
|
||||
|
||||
3) Look for the "$apps = array();" line. Below it will be a series of items,
|
||||
which are the data used for each app shown in the front page screenshots.
|
||||
|
||||
Add a new line at the bottom, with the following format:
|
||||
|
||||
$apps[] = array(appname, appurl, array(screenshot1, screenshot2, ...));
|
||||
|
||||
The screenshot1, etc. filenames should not have any path to them. They should
|
||||
just be the filename. The actual shown screenshot is chosen at random from
|
||||
the list of screenshots, so order, etc. doesn't matter.
|
||||
|
||||
Once you've done this, the new app w/screenshots should appear on the front page!
|
||||
@ -1,54 +1 @@
|
||||
How to add a new XRC handler
|
||||
============================
|
||||
|
||||
0. Purpose
|
||||
----------
|
||||
|
||||
This note describes what needs to be done to add a new XRC handler, i.e. add
|
||||
support for loading the objects of some class wxFoo from XRC.
|
||||
|
||||
|
||||
1. Implement the handler
|
||||
------------------------
|
||||
|
||||
By convention, the XRC handler for a class wxFoo declared in wx/foo.h is called
|
||||
wxFooXmlHandler and is declared in the file wx/xrc/xh_foo.h (this last rule
|
||||
wasn't always respected in the past, however it's not a reason to not respect
|
||||
it in the future). The steps for adding a new handler are:
|
||||
|
||||
a) Add handler declaration in include/wx/xrc/xh_foo.h, it will usually be the
|
||||
same as in the other files so you can get inspiration for your brand new
|
||||
handler from e.g. wx/xrc/xh_srchctrl.h. Notice the use of wxUSE_FOO if wxFoo
|
||||
is guarded by this symbol.
|
||||
|
||||
b) Add implementation in src/xrc/xh_foo.cpp: again, it will be almost always
|
||||
very similar to the existing controls. You will need to add support for
|
||||
the control-specific styles.
|
||||
|
||||
|
||||
2. Update the other files
|
||||
-------------------------
|
||||
|
||||
There are a few other files to update to make wxWidgets aware of the new
|
||||
handler:
|
||||
|
||||
a) Add the new files created above to build/bakefiles/files.bkl: search for
|
||||
"xh_srchctrl" to see where you need to add them
|
||||
|
||||
b) Add #include "wx/xrc/xh_foo.h" to wx/xrc/xh_all.h.
|
||||
|
||||
c) Register the new handler in wxXmlResource::InitAllHandlers() in
|
||||
src/xrc/xmlrsall.cpp
|
||||
|
||||
|
||||
3. Update the sample
|
||||
--------------------
|
||||
|
||||
Demonstrate that the new handler works by adding a control using it to
|
||||
samples/xrc/rc/controls.xrc.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: VZ
|
||||
|
||||
Please see index.txt
|
||||
|
||||
@ -1,127 +1 @@
|
||||
How to update a third party library to a newer version
|
||||
======================================================
|
||||
|
||||
0. Introduction
|
||||
---------------
|
||||
|
||||
wxWidgets includes several third party libraries, i.e. libraries which are
|
||||
used by wxWidgets and distributed with it but which we don't maintain nor even
|
||||
modify, inasmuch as possible, ourselves. These libraries are developed by
|
||||
their maintainers and from time to time we need to replace the versions used
|
||||
by wxWidgets with newer versions.
|
||||
|
||||
|
||||
1. Vendor branches
|
||||
------------------
|
||||
|
||||
Normally all third party libraries should be managed using Subversion vendor
|
||||
branches. I.e. we should have the latest version of the library under
|
||||
/wx/wxWidgets/vendor directory in the repository. Currently only expat, libpng
|
||||
and libtiff are handled like this, while libjpeg and zlib are not. Hopefully
|
||||
these exceptions will disappear soon, the rest of this note assumes that we
|
||||
are using a vendor branch for the library $(LIB).
|
||||
|
||||
We also use $(OLD_VERSION) and $(VERSION) below for the current version of the
|
||||
library and the version we are upgrading to. $(OLD_VERSION) can be determined
|
||||
by doing
|
||||
|
||||
svn ls https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)
|
||||
|
||||
as normally it's the latest version present in this directory. You can, of
|
||||
course, also look at the library sources currently in the trunk to find out
|
||||
its version.
|
||||
|
||||
|
||||
NB: the instructions here are based on the Subversion documentation, see
|
||||
http://svnbook.red-bean.com/en/1.6/svn.advanced.vendorbr.html for more
|
||||
information about vendor branches.
|
||||
|
||||
|
||||
2. Updating the current branch
|
||||
------------------------------
|
||||
|
||||
The first thing to do is to checkout a pristine copy of the version currently
|
||||
being used, e.g.
|
||||
|
||||
cd /some/temp/directory
|
||||
svn checkout https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current $(LIB)
|
||||
|
||||
Now delete all the old files:
|
||||
|
||||
cd $(LIB)
|
||||
find . -type f -not -path '*/.svn/*' -exec rm {} \;
|
||||
|
||||
or, if you are using zsh, just
|
||||
|
||||
rm **/*(.)
|
||||
|
||||
Next, get the version of the library you are updating to and unpack it into
|
||||
the same directory. Examine "svn status" output and add all the files with "?"
|
||||
in the first column using "svn add" and delete all the files with "!" in the
|
||||
first column using "svn rm".
|
||||
|
||||
Finally commit and tag the new version:
|
||||
|
||||
svn commit -m 'Update $(LIB) to $(VERSION).'
|
||||
svn cp https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current \
|
||||
https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/$(VERSION) \
|
||||
-m 'Tagging $(LIB) $(VERSION).'
|
||||
|
||||
You can now do
|
||||
|
||||
rm -rf /some/temp/directory/$(LIB)
|
||||
|
||||
as it won't be needed any longer.
|
||||
|
||||
|
||||
3. Merging the current branch
|
||||
-----------------------------
|
||||
|
||||
Now switch to wxWidgets checkout and run
|
||||
|
||||
svn merge ^/wxWidgets/vendor/$(LIB)/$(OLD_VERSION) ^/wxWidgets/vendor/$(LIB)/current src/$(LIBDIR)
|
||||
|
||||
Notice that you may need to escape the circumflexes with backslashes if they
|
||||
are special for your shell. Also notice that the directory of the library may
|
||||
be different from its name, e.g. we use libpng for the vendor branch but just
|
||||
png for the name of the directory.
|
||||
|
||||
Unless you are very lucky, the merge will result in conflicts and you will
|
||||
need to resolve them by examining the differences -- this is the difficult
|
||||
part.
|
||||
|
||||
Once everything was resolved, test your changes. As building the third party
|
||||
libraries is quite different between Unix and Windows, please do it under both
|
||||
platforms. Under Windows it's enough to just build everything as usual as the
|
||||
built-in libraries are used by default. Please build both static and dynamic
|
||||
wxWidgets libraries as some problems arise only in one of those configurations.
|
||||
Under Unix you need to configure with --with-$(LIB)=builtin option to ensure
|
||||
that the newly updated built-in version of the library is used and not the
|
||||
system version. If upgrading an image format library, please build and run the
|
||||
image sample. In any case, run the unit tests to check that everything still
|
||||
works.
|
||||
|
||||
After testing and correcting the problems, simply commit your changes:
|
||||
|
||||
svn commit -m 'Update $(LIB) to $(VERSION).' src/$(LIBDIR)
|
||||
|
||||
|
||||
4. Special instructions for libpng
|
||||
----------------------------------
|
||||
|
||||
We use a special hack for libpng as we want to prefix all its symbols with
|
||||
"wx_" but don't want to use its build system which makes this easily possible
|
||||
(perhaps we should, but for now we don't). So, when upgrading libpng, you need
|
||||
to perform an extra step after merging the new version (and before committing
|
||||
your changes):
|
||||
|
||||
Create a temporary build directory and run libpng configure from it using
|
||||
--with-libpng-prefix=wx_ option. Then run "make" (actually just "make png.lo"
|
||||
is sufficient as we don't really need to build the library) to create
|
||||
pnglibconf.h and pngprefix.h files in the build directory. And copy these
|
||||
files to src/png subdirectory of the wxWidgets source tree, overwriting the
|
||||
versions there.
|
||||
|
||||
Notice that config.h generated by libpng configure is not used, we build it
|
||||
without -DHAVE_CONFIG_H as it works just fine without it on any ANSI C system
|
||||
(i.e. anywhere by now).
|
||||
Please see index.txt
|
||||
|
||||
Loading…
Reference in New Issue
Block a user