docs/x11/readme-nanox.txt

   1 Nano-X port
   2 ===========
   3
   4 What is it?
   5 ===========
   6
   7 The Nano-X port is based on the wxX11 code, and therefore shares
   8 almost all of wxX11's code, including the use of the wxUniversal
   9 widget set. Nano-X is the X-like API of the overall Microwindows
  10 project, which also has a WIN32 API.
  11
  12 The Microwindows web site is at
  13
  14         http://microwindows.org/
  15
  16 Nano-X is intended to work on devices with very small amounts
  17 of memory. wxWidgets is quite a large library, so if your
  18 memory is measured in KB instead of MB you will need to use
  19 an alternative library, such as FLTK. However, with memory
  20 capacity increasing all the time, wxWidgets could become
  21 an appropriate embedded GUI solution for many projects.
  22 Also, it's possible to think of ways to cut wxWidgets
  23 further down to size, such as disabling advanced controls
  24 or rewriting utility functions. See the section on code size
  25 below.
  26
  27 An alternative to using Nano-X is to use the standard
  28 wxX11 port with Tiny-X, which (as I understand it)
  29 maintains the Xlib API while being sufficiently cut
  30 down to run on small devices, such as the iPAQ.
  31 The Familiar Linux Distribution contains Tiny-X. See:
  32
  33         http://handhelds.org/mailman/listinfo/familiar
  34
  35 Building wxNano-X
  36 =================
  37
  38 Building is as per the instructions for wxX11 (see readme.txt,
  39 install.txt) but passing --enable-nanox to configure.  You also need
  40 to export the MICROWIN variable, setting it to the top-level of the
  41 Microwindows hierarchy. Remember that MICROWIN needs to be defined
  42 both at configuration time and at subsequent make time, so you
  43 may find it convenient to put it in your .bash_profile or similar
  44 file.
  45
  46 Typically, various features in wxWidgets will be switched off to
  47 conserve space. The sample script below calls configure with typical
  48 options for Nano-X.
  49
  50 Before compiling wxNano-X, you will also need to edit your
  51 Microwindows 'config' file to match the values hard-coded into
  52 configure:
  53
  54   ERASEMOVE=N (otherwise moving windows will look messy)
  55   X11=Y
  56   OPTIMIZE=N
  57   DEBUG=Y
  58   VERBOSE=Y
  59
  60 Compile Microwindows by typing 'make' from within the Microwindows src
  61 directory.
  62
  63 Port notes
  64 ==========
  65
  66 Nano-X has a different API from Xlib, although there
  67 are many similarities. Instead of changing the wxWidgets
  68 code to reflect Nano-X conventions, a compatibility
  69 layer has been added, in the form of these files:
  70
  71 include/wx/x11/nanox/X11/Xlib.h  ; Xlib compatibility
  72 include/wx/x11/privx.h           ; Useful macros
  73 src/x11/nanox.c                  ; Xlib compatibility
  74
  75 There is also an XtoNX.h compatibility header file
  76 in Microwindows, which we augment with our Xlib.h
  77 and nanox.c.
  78
  79 Unfortunately it is not always possible, or economical,
  80 to provide a complete Xlib emulation, so there are
  81 still wxUSE_NANOX preprocessor directives in the code
  82 for awkward cases. It may be possible to eliminate
  83 some, but probably not all, of these in future.
  84
  85 Port Status
  86 ===========
  87
  88 The port is in a very early stage: so far it links
  89 and a window pops up, but that's about it. (The
  90 wxX11 port using straight X11 is much more advanced.)
  91
  92 Things 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
 105 Code Size
 106 =========
 107
 108 Allow about 2.5 MB for a shared wxWidgets library, with the
 109 dynamically linked minimal sample taking about 24KB. If statically
 110 linked, minimal takes up just over 1MB when stripped. This 1MB
 111 includes all of wxWidgets used in the minimal sample including some of
 112 the wxUniversal widgets. As application complexity increases,
 113 the amount of wxWidgets code pulled into statically linked
 114 executables increases, but for large applications, the overhead
 115 of wxWidgets becomes less significant.
 116
 117 Sample sizes:
 118 -------------
 119
 120 Statically-linked minimal (release): 1,024,272 bytes
 121 Statically-linked widgets (release): 1,171,568 bytes
 122
 123 Shared lib, stripped (debug): 2,486,716 bytes
 124 Shared-lib minimal (debug), stripped: 23,896 bytes
 125
 126 Shared lib, stripped (release): 2,315,5004 bytes
 127 Shared-lib minimal (release), stripped: 23,896 bytes
 128 (note: the -O flag was not passed to the minimal
 129 makefile, for some reason)
 130
 131 Strategies 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
 145   wxWidgets.
 146 - Factor out wxWidgets code to reduce repetition.
 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
 161 Sample script for building wxNano-X
 162 ===================================
 163
 164 This script assumes that you will invoke it
 165 from a build directory under the wxWidgets
 166 top level. So you might type:
 167
 168 % cd wx2
 169 % mkdir nano-x
 170 % cd nano-x
 171 % makewxnanox
 172
 173 If you need to restart compilation without
 174 reconfiguring, just type 'make' from the same
 175 directory.
 176
 177 -----------------------------:x----------------------
 178
 179 #!/bin/sh
 180 # makewxnanox
 181
 182 export MICROWIN=/home/julians/microwindows/microwindows-0.89pre8
 183
 184 #DEBUGFLAGS="--enable-debug --enable-debug_cntxt --disable-optimise"
 185 DEBUGFLAGS="--disable-debug --disable-debug_cntxt --enable-optimise"
 186
 187 export 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
 189 echo $CONFIGCMD
 190 if [ ! -f ./configure ]; then
 191   CONFIGCMD=".$CONFIGCMD"
 192 fi
 193
 194 echo Invoking $CONFIGCMD
 195
 196 rm -f *.cache
 197 $CONFIGCMD
 198
 199 make
 200
 201 -----------------------------:x----------------------