Add wxX11EventLoopSourcesManager stub implementation to fix wxX11 linking.
[wxWidgets.git] / docs / x11 / readme-nanox.txt
CommitLineData
0fccf28f
JS
1Nano-X port
2===========
3
4What is it?
5===========
6
7The Nano-X port is based on the wxX11 code, and therefore shares
8almost all of wxX11's code, including the use of the wxUniversal
9widget set. Nano-X is the X-like API of the overall Microwindows
10project, which also has a WIN32 API.
11
12The Microwindows web site is at
13
14 http://microwindows.org/
15
16Nano-X is intended to work on devices with very small amounts
fc2171bd 17of memory. wxWidgets is quite a large library, so if your
0fccf28f
JS
18memory is measured in KB instead of MB you will need to use
19an alternative library, such as FLTK. However, with memory
fc2171bd 20capacity increasing all the time, wxWidgets could become
0fccf28f 21an appropriate embedded GUI solution for many projects.
fc2171bd 22Also, it's possible to think of ways to cut wxWidgets
0fccf28f
JS
23further down to size, such as disabling advanced controls
24or rewriting utility functions. See the section on code size
25below.
26
27An alternative to using Nano-X is to use the standard
28wxX11 port with Tiny-X, which (as I understand it)
29maintains the Xlib API while being sufficiently cut
30down to run on small devices, such as the iPAQ.
31The Familiar Linux Distribution contains Tiny-X. See:
32
33 http://handhelds.org/mailman/listinfo/familiar
34
35Building wxNano-X
36=================
37
38Building is as per the instructions for wxX11 (see readme.txt,
39install.txt) but passing --enable-nanox to configure. You also need
40to export the MICROWIN variable, setting it to the top-level of the
41Microwindows hierarchy. Remember that MICROWIN needs to be defined
42both at configuration time and at subsequent make time, so you
43may find it convenient to put it in your .bash_profile or similar
44file.
45
fc2171bd 46Typically, various features in wxWidgets will be switched off to
0fccf28f
JS
47conserve space. The sample script below calls configure with typical
48options for Nano-X.
49
50Before compiling wxNano-X, you will also need to edit your
51Microwindows 'config' file to match the values hard-coded into
52configure:
53
54 ERASEMOVE=N (otherwise moving windows will look messy)
55 X11=Y
56 OPTIMIZE=N
57 DEBUG=Y
58 VERBOSE=Y
59
60Compile Microwindows by typing 'make' from within the Microwindows src
61directory.
62
63Port notes
64==========
65
66Nano-X has a different API from Xlib, although there
fc2171bd 67are many similarities. Instead of changing the wxWidgets
0fccf28f
JS
68code to reflect Nano-X conventions, a compatibility
69layer has been added, in the form of these files:
70
71include/wx/x11/nanox/X11/Xlib.h ; Xlib compatibility
72include/wx/x11/privx.h ; Useful macros
73src/x11/nanox.c ; Xlib compatibility
74
75There is also an XtoNX.h compatibility header file
76in Microwindows, which we augment with our Xlib.h
77and nanox.c.
78
79Unfortunately it is not always possible, or economical,
80to provide a complete Xlib emulation, so there are
81still wxUSE_NANOX preprocessor directives in the code
82for awkward cases. It may be possible to eliminate
83some, but probably not all, of these in future.
84
85Port Status
86===========
87
88The port is in a very early stage: so far it links
89and a window pops up, but that's about it. (The
90wxX11 port using straight X11 is much more advanced.)
91
92Things to do:
93
94- implement some incomplete compatibility functions
95 in src/x11/nanox.c
96- implement the colour database
97- add mask capability, without which controls won't
98 display properly
99- add further configuration options for disabling
100 code not normally needed in an embedded device
101- optimization and code size reduction
102- figuring out why libstdc++-libc is linked to
103 binaries -- is this done for any C++ program?
104
105Code Size
106=========
107
fc2171bd 108Allow about 2.5 MB for a shared wxWidgets library, with the
0fccf28f
JS
109dynamically linked minimal sample taking about 24KB. If statically
110linked, minimal takes up just over 1MB when stripped. This 1MB
fc2171bd 111includes all of wxWidgets used in the minimal sample including some of
0fccf28f 112the wxUniversal widgets. As application complexity increases,
fc2171bd 113the amount of wxWidgets code pulled into statically linked
0fccf28f 114executables increases, but for large applications, the overhead
fc2171bd 115of wxWidgets becomes less significant.
0fccf28f
JS
116
117Sample sizes:
118-------------
119
120Statically-linked minimal (release): 1,024,272 bytes
121Statically-linked widgets (release): 1,171,568 bytes
122
123Shared lib, stripped (debug): 2,486,716 bytes
124Shared-lib minimal (debug), stripped: 23,896 bytes
125
126Shared lib, stripped (release): 2,315,5004 bytes
127Shared-lib minimal (release), stripped: 23,896 bytes
128(note: the -O flag was not passed to the minimal
129makefile, for some reason)
130
131Strategies for reducing code size
132---------------------------------
133
134- Look at the .o files compiled in a build and check
135 for particularly large files, or files you wouldn't
136 expect to be there in an embedded build.
137- Disable options for features that aren't necessary,
138 for example: image handlers (BMP, JPEG etc.),
139 wxVariant, wxWizard, wxListCtrl, src/univ/themes/gtk.c.
140- Add options to configure.in/setup.h where necessary,
141 for finer-grained configuration.
142- Rewrite functions or classes for alternative stripped-down
143 functionality.
144- Remove unnecessary functionality or obsolete code from
fc2171bd
JS
145 wxWidgets.
146- Factor out wxWidgets code to reduce repetition.
0fccf28f
JS
147- Add inlining, remove unnecessary empty functions.
148- Separate code out into individual files so that all of
149 a .o file doesn't get pulled in, just because an app
150 references something else in that file. For example,
151 advanced event types could be separated out.
152 This assumes that the linker isn't clever enough to
153 eliminate redundant functions. The fact that the
154 minimal and widgets samples are very close in size
155 is evidence that gcc is not doing a good job here.
156- Experiment with compiler options.
157- Commercially supported compilers may have better
158 code generation and/or linker optimisation than the
159 one you're currently using.
160
161Sample script for building wxNano-X
162===================================
163
164This script assumes that you will invoke it
fc2171bd 165from a build directory under the wxWidgets
0fccf28f
JS
166top level. So you might type:
167
168% cd wx2
169% mkdir nano-x
170% cd nano-x
171% makewxnanox
172
173If you need to restart compilation without
174reconfiguring, just type 'make' from the same
175directory.
176
177-----------------------------:x----------------------
178
179#!/bin/sh
180# makewxnanox
181
182export MICROWIN=/home/julians/microwindows/microwindows-0.89pre8
183
184#DEBUGFLAGS="--enable-debug --enable-debug_cntxt --disable-optimise"
185DEBUGFLAGS="--disable-debug --disable-debug_cntxt --enable-optimise"
186
187export CONFIGCMD="./configure $DEBUGFLAGS --enable-shared --enable-gui --with-x11 --enable-nanox --enable-log --with-threads --without-sockets --without-odbc --without-libjpeg --without-libtiff --without-png --without-regex --enable-no_exceptions --disable-protocols --disable-ipc --disable-dialupman --disable-apple_ieee --disable-fraction --disable-dynlib --disable-dynamicloader --disable-geometry --disable-fontmap --disable-std_iostreams --disable-filesystem --disable-fs_inet --disable-fs_zip --disable-zipstream --disable-snglinst --disable-mimetype --disable-url --disable-html --disable-constraints --disable-printarch --disable-mdi --disable-postscript --disable-PS-normalized --disable-afmfonts --disable-prologio --disable-resources --disable-dnd --disable-metafile --disable-treelayout --disable-grid --disable-propsheet --disable-splines --disable-joystick --disable-pcx --disable-iff --disable-pnm --disable-tabdialog --disable-newgrid"
188
189echo $CONFIGCMD
190if [ ! -f ./configure ]; then
191 CONFIGCMD=".$CONFIGCMD"
192fi
193
194echo Invoking $CONFIGCMD
195
196rm -f *.cache
197$CONFIGCMD
198
199make
200
201-----------------------------:x----------------------