Mercurial > flash_v2
annotate README.host @ 441:41489edbdf76
* src/vectors.S: Added GRUB startup option to tests for IDT
initialization. Added call to breakpoint() before cyg_start(),
controlled by CYGDBG_HAL_DEBUG_GDB_INITIAL_BREAK.
| author | nickg |
|---|---|
| date | Sun, 01 Dec 2002 15:50:14 +0000 |
| parents | 3f4258400ba5 |
| children | def85e4d96d2 |
| rev | line source |
|---|---|
| 290 | 1 eCos Host-side Software |
| 2 ======================= | |
| 3 | |
| 4 This README file only describes the eCos host-side software. For | |
| 5 details of the eCos target-side software or the required toolchains, | |
| 6 please see other documentation. A good starting point is | |
| 7 http://sources.redhat.com/ecos | |
| 8 | |
| 9 There are two categories of host-side software. The host subdirectory | |
| 10 contains generic software, primarily related to the eCos configuration | |
| 11 technology. All eCos users will need to use some of this technology to | |
| 12 configure and build eCos, either using pre-built binaries or by | |
| 13 building the host-side software from source. The generic software | |
| 14 should be portable to a wide range of host platforms. | |
| 15 | |
| 16 There is also package-specific host-side software. Much of this is I/O | |
| 17 related. For example the generic USB-slave package contains some | |
| 18 programs related to testing; a test application is run on a target | |
| 19 with suitable USB slave-side hardware, and needs to interact with | |
| 20 another program running on the USB host; the latter is | |
| 21 package-specific host-side software and can be found in the | |
| 22 subdirectory packages/io/usb/slave. Code like this may have | |
| 23 significant platform dependencies and may only work on a single | |
| 24 platform or on a small number of platforms. There may also be | |
| 25 special requirements, for example it may be necessary to install some | |
| 26 programs suid root so that they have appropriate access to the | |
| 27 hardware. | |
| 28 | |
| 29 | |
| 30 The host subdirectory includes the following: | |
| 31 | |
| 32 infra/ | |
| 33 This is an implementation of the eCos infrastructure that can be | |
| 34 used on the host-side, and provides assertion, tracing and | |
| 35 testcase support. | |
| 36 | |
| 37 NOTE: the eCos infrastructure facilities are not especially | |
| 38 well-suited to host-side development, in particular they are not | |
| 39 C++-oriented. There are plans to remove the current infrastructure | |
| 40 completely and replace it with something more suitable. People | |
| 41 planning new projects should be aware of this, and may wish to | |
| 42 avoid using the current infrastructure. | |
| 43 | |
| 44 libcdl/ | |
| 45 The CDL library lies at the heart of the eCos configuration | |
| 46 technology. | |
| 47 | |
| 48 tools/configtool/ | |
| 49 The sources to the various configuration tools can be found here. | |
| 50 | |
| 51 tools/configtool/common/common/ | |
| 52 Contains sources related to makefile generation, shared by the | |
| 53 command line and graphical tools. | |
| 54 | |
| 55 tools/configtool/standalone/common/ | |
| 56 Contains the command line ecosconfig tool. | |
| 57 | |
| 58 tools/configtool/standalone/wxwin/ | |
| 59 Contains sources for the wxWindows-based, Linux and Windows graphical | |
| 60 configuration tool. The Windows version can currently only be | |
| 61 built with Visual C++, not with cygwin g++. | |
| 62 | |
| 63 tools/configtool/common/win32/ | |
| 64 tools/configtool/standalone/win32/ | |
| 65 Contains sources for the older, MFC-based, Windows-only graphical | |
| 66 configuration tool. Again this can currently only be built with | |
| 67 Visual C++. | |
| 68 | |
| 69 The two graphical configuration tools have their own build procedures, | |
| 70 described in tools/configtool/standalone/wxwin/ReadMe and | |
| 71 tools/configtool/standalone/win32/ReadMe respectively. | |
| 72 | |
| 73 Package-specific host-side code lives in the host subdirectory of the | |
| 74 appropriate package, for example packages/io/usb/slave/<version>/host. | |
| 75 Most packages only provide target-side code and hence will not have a | |
| 76 host subdirectory. Users can install various packages from a variety | |
| 77 of sources, and where a package does have host-side software the | |
| 78 package documentation should be consulted for further information. | |
| 79 | |
| 80 | |
| 81 Installing on Linux and Other Unix Systems | |
| 82 ------------------------------------------ | |
| 83 | |
| 84 Both generic host-side software (infra, libcdl and ecosconfig) and | |
| 85 package-specific software can be built with the conventional | |
| 86 "configure/make/make install" sequence. However the code does not | |
| 87 conform fully to GNU coding standards so some operations such as "make | |
| 88 dist" are not supported. There is limited support for DejaGnu-based | |
| 89 testing. | |
| 90 | |
| 91 Much of the host-side software has a dependency on Tcl. This is not | |
| 92 supplied with the sources since many users will already have a | |
|
345
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
93 suitable installation, for example it is shipped as standard with all |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
94 major Linux distributions. The generic host-side software should work |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
95 with any release of Tcl from 8.0 onwards. The package-specific |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
96 software requires a more recent version, 8.3 or later. If no suitable |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
97 Tcl installation is available then the configure step will still |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
98 succeed but some of the package-specific software will not be built. |
| 290 | 99 |
| 100 There are two main approaches to building the host-side software: | |
| 101 | |
| 102 1) build the generic and the package-specific code in one build tree. | |
| 103 This uses the top-level configure script. The script automatically | |
| 104 invokes the configure script in the main host subdirectory. In | |
| 105 addition it searches the packages hierarchy for host subdirectories | |
| 106 containing their own configure scripts and will invoke those. | |
| 107 | |
| 108 Note: the search for host subdirectories happens during configure | |
| 109 time, not during the make. If new packages with host-side code are | |
| 110 added to the repository then it will be necessary to re-run the | |
| 111 toplevel configure script. | |
| 112 | |
| 113 2) build the generic code in one build tree, using the configure | |
| 114 script in the toplevel's host subdirectory. Then build some or all | |
| 115 of the package-specific code in separate build trees, using the | |
| 116 configure scripts in each package's host subdirectory. | |
| 117 | |
| 118 The first approach is generally simpler. However some of the | |
| 119 package-specific code requires special installation, for example a | |
| 120 program may have to be installed suid root so that it has the right | |
| 121 privileges to access hardware, and hence the "make install" step has | |
| 122 to be run by the superuser. Also some of the package-specific code is | |
| 123 rather specialized and may be of no interest to many users. For | |
| 124 example, the USB testing code is only useful when developing | |
| 125 USB-based applications. Hence some users may prefer the second | |
| 126 approach, building just the generic code and a subset of the | |
| 127 package-specific code. | |
| 128 | |
| 129 It is necessary to use a separate build tree rather than build | |
| 130 directly in the source tree. This is enforced by the configure scripts. | |
| 131 | |
| 132 $ mkdir build | |
| 133 $ cd build | |
| 134 | |
| 135 The next step is to run the desired configure script. To build all | |
| 136 the host-side software this means the toplevel configure script: | |
| 137 | |
| 138 $ <path>/configure <args> | |
| 139 | |
| 140 Alternatively to build just the generic host-side software, use the | |
| 141 configure script in the host subdirectory. | |
| 142 | |
| 143 $ mkdir host | |
| 144 $ cd host | |
| 145 $ <path>/host/configure <args> | |
| 146 | |
| 147 Or, to build just one package's host-side code: | |
| 148 | |
| 149 $ mkdir -p packages/io/usb/slave/current/host | |
| 150 $ cd packages/io/usb/slave/current/host | |
| 151 $ <path>/packages/io/usb/slave/current/host/configure <args> | |
| 152 | |
| 153 (It is not actually necessary to use the same directory structure in | |
| 154 the build tree as in the source tree, but doing so can avoid | |
| 155 confusion). | |
| 156 | |
| 157 A list of all the command-line options can be obtained by running | |
| 158 "configure --help". The most important ones are as follows: | |
| 159 | |
| 160 1) --prefix. This can be used to specify the location of the install | |
| 161 tree, defaulting to /usr/local, so the ecosconfig program ends up | |
| 162 in /usr/local/bin/ecosconfig and the CDL library ends up in | |
| 163 /usr/local/lib/libcdl.a. If an alternative location is preferred | |
| 164 this can be specified with --prefix, for example: | |
| 165 | |
| 166 $ <path>/configure --prefix=/usr/local/ecos <args> | |
| 167 | |
| 168 2) --enable-debug. By default all assertions and tracing are disabled. | |
| 169 When debugging any of the generic host-side software these should | |
| 170 be enabled. Some package-specific code may not have any extra | |
| 171 debug support, in which case --enable-debug would be ignored. | |
| 172 | |
| 173 $ <path>/configure --enable-debug | |
| 174 | |
| 175 It is also possible to control most of the assertion and tracing | |
| 176 macros at a finer grain. This is intended mainly for use by the | |
| 177 developers. | |
| 178 | |
| 179 --disable-asserts disable all assertions | |
| 180 --disable-preconditions disable a subset of the assertions | |
| 181 --disable-postconditions disable a subset of the assertions | |
| 182 --disable-invariants disable a subset of the assertions | |
| 183 --disable-loopinvariants disable a subset of the assertions | |
| 184 --disable-tracing disable tracing | |
| 185 --disable-fntracing disable function entry/exit tracing | |
| 186 | |
| 187 3) --with-tcl=<path> | |
| 188 --with-tcl-header=<path> | |
| 189 --with-tcl-lib=<path> | |
| 190 --with-tcl-version=<number> | |
| 191 | |
| 192 The host-side tools have a dependency on Tcl, which is not supplied | |
| 193 with the sources because many people will already have a suitable | |
| 194 installation. Specifically it is necessary to have the header file | |
| 195 tcl.h and appropriate libraries such that -ltcl will work - this | |
| 196 can involve either static or shared libraries. | |
| 197 | |
| 198 By default the configure script will assume that there is a | |
| 199 suitable Tcl installation in the install location, so if there is | |
| 200 no --prefix argument then it will look for /usr/local/include/tcl.h | |
| 201 and it will add -L/usr/local/lib to the library search path. If | |
| 202 Tcl is installed elsewhere then this can be specified with a | |
| 203 --with-tcl option. For example, if the default installation in | |
| 204 /usr should be used then the following configure option is | |
| 205 appropriate: | |
| 206 | |
| 207 $ <path>/configure --with-tcl=/usr <args> | |
| 208 | |
| 209 If the Tcl libraries and Tcl headers are installed in different | |
| 210 locations, such as when a separate --prefix and --exec-prefix are | |
| 211 used, the --with-tcl-header and --with-tcl-lib options can be used | |
| 212 to specify both location. The configure script will expect to find | |
| 213 <tcl-header-dir>/include/tcl.h and <tcl-lib-dir>/lib/tclConfig.sh. | |
| 214 The --with-tcl option has precedence and if used will override the | |
| 215 --with-tcl-header and --with-tcl-lib options. | |
| 216 | |
| 217 It is possible to have multiple versions of Tcl installed, for | |
| 218 example libtcl8.0.a, libtcl8.1.a, and so on. Typically linking with | |
| 219 -ltcl will result in the latest version being used. It is possible | |
| 220 to specify a different version using --with-tcl-version, e.g.: | |
| 221 | |
| 222 $ <path>configure --with-tcl=/usr/local/scriptics --with-tcl-version=8.1 <args> | |
| 223 | |
|
345
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
224 It may be necessary to specify --with-tcl-version if there are |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
225 multiple installs in different locations. For example the |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
226 system may have a default install in /usr and a more up to date |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
227 install in /usr/local/tcl8.4. To use the latter it will usually |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
228 be necessary to specify both --with-tcl=/usr/local/tcl8.4 and |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
229 --with-tcl-version=8.4. |
|
3f4258400ba5
Fix host-side configury problems which can occur if you are not using
bartv
parents:
290
diff
changeset
|
230 |
| 290 | 231 Following the configure step the build tree should be set up |
| 232 correctly. All that remains is the actual build and install: | |
| 233 | |
| 234 $ make | |
| 235 $ make install | |
| 236 | |
| 237 This should result in an ecosconfig executable, plus appropriate | |
| 238 libraries and header files. If the install prefix is a system | |
| 239 location, for example /usr/local/, then "make install" will normally | |
| 240 require root privileges. Also some of the package-specific software | |
| 241 has special installation requirements, for example programs that need | |
| 242 to be installed suid root, and this will also need root privileges. | |
| 243 | |
| 244 | |
| 245 Installing under Cygwin | |
| 246 ----------------------- | |
| 247 | |
| 248 Installing under cygwin requires essentially the same steps as | |
| 249 under Linux. It is more likely that a suitable --prefix option will | |
| 250 have to be used, and that the location of the Tcl installation needs | |
| 251 to be specified with --with-tcl. However appropriate use of cygwin | |
| 252 mount points may avoid some of these problems. If the full path to | |
| 253 the configure script contains spaces, then the short form of the path | |
| 254 should be used when invoking configure. | |
| 255 | |
| 256 One issue to be aware of is the naming convention for the Tcl library. | |
| 257 On a Unix system this will typically be called libtcl8.3.a (adjusted | |
| 258 according to the version number), with a symbolic link from libtcl.a | |
| 259 to the most recent version. Under cygwin the equivalent library is | |
| 260 called libtcl80.a, and symbolic links are not used. For a standard | |
| 261 cygwin installation the configure script knows how to pick up the | |
| 262 appropriate library, but if a more recent version of Tcl has been | |
| 263 installed then due care has to be taken with the --with-tcl-version | |
| 264 option. | |
| 265 | |
| 266 | |
| 267 Installing with Visual C++ | |
| 268 -------------------------- | |
| 269 | |
| 270 Under Windows it is possible to build the generic host-side software | |
| 271 (infra, libcdl and ecosconfig) with Visual C++ but this is deprecated. | |
| 272 Building with g++ under cygwin is preferred. | |
| 273 | |
| 274 It is still necessary to run the configure script and a suitable make | |
| 275 utility. That requires a shell and a Unix-like environment, as | |
| 276 provided by cygwin. The Visual C++ compiler cl.exe needs to be on the | |
| 277 shell's search path, and some environment variables such as INCLUDE | |
| 278 and LIB may need to be set to point at the Visual C++ installation - | |
| 279 the details may vary depending on the version of the compiler. Then | |
| 280 the configure command should be run like this: | |
| 281 | |
| 282 $ CC=cl CXX=cl <path>/host/configure <args> | |
| 283 | |
| 284 Note that the path should be a cygwin path: cygwin mount points are | |
| 285 accepted and forward slashes should be used. The various configure | |
| 286 scripts now detect that Visual C++ should be used, and adapt | |
| 287 accordingly. | |
| 288 | |
| 289 Depending on what cygwin mount points are set up, /usr/local may or | |
| 290 may not be an appropriate install location for VC++ applications. | |
| 291 If not, the install location should be specified with --prefix: | |
| 292 | |
| 293 $ CC=cl CXX=cl <path>/configure --prefix=<install-path> <args> | |
| 294 | |
| 295 It is also necessary to use the right version of Tcl. For a VC++ build | |
| 296 the cygwin release of Tcl should not be used. Instead a suitable | |
| 297 prebuilt Tcl package can be obtained from http://www.scriptics.com/. | |
| 298 It is necessary to tell the configure script where this has been | |
| 299 installed, for example: | |
| 300 | |
| 301 $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \ | |
| 302 --with-tcl=/cygdrive/d/local/scriptics/Tcl/tcl8.1 <args> | |
| 303 | |
| 304 The library name will be of the form tcl81.lib, and there will not be | |
| 305 a symbolic link from tcl.lib to the appropriate version. It will be | |
| 306 necessary to specify the Tcl version explicitly since the default | |
| 307 version is currently 8.0. | |
| 308 | |
| 309 $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \ | |
| 310 --with-tcl=/d/local/scriptics/Tcl/tcl8.1 --with-tcl-version=81 <args> | |
| 311 | |
| 312 Following a successful configure, the tools can be built and installed | |
| 313 in the normal fashion: | |
| 314 | |
| 315 $ make | |
| 316 $ make install | |
| 317 | |
| 318 | |
| 319 More Information | |
| 320 ================ | |
| 321 | |
| 322 Please see the eCos web site, http://sources.redhat.com/ecos/, for | |
| 323 further details. This includes the FAQ, a form for reporting problems, | |
| 324 and details of the various mailing lists | |
| 325 (http://sources.redhat.com/ecos/intouch.html) At the time of writing | |
| 326 there are no separate mailing lists for the eCos host-side sources, | |
| 327 the main mailing list ecos-discuss@sources.redhat.com should be used | |
| 328 instead. | |
| 329 | |
| 330 //####COPYRIGHTBEGIN#### | |
| 331 // | |
| 332 //---------------------------------------------------------------------------- | |
| 333 // Copyright (C) 2002 Bart Veer | |
| 334 // Copyright (C) 2000, 2001 Red Hat, Inc. | |
| 335 // | |
| 336 // This file is part of the eCos host tools. | |
| 337 // | |
| 338 // This program is free software; you can redistribute it and/or modify it | |
| 339 // under the terms of the GNU General Public License as published by the Free | |
| 340 // Software Foundation; either version 2 of the License, or (at your option) | |
| 341 // any later version. | |
| 342 // | |
| 343 // This program is distributed in the hope that it will be useful, but WITHOUT | |
| 344 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 345 // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for | |
| 346 // more details. | |
| 347 // | |
| 348 // You should have received a copy of the GNU General Public License along with | |
| 349 // this program; if not, write to the Free Software Foundation, Inc., | |
| 350 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. | |
| 351 // | |
| 352 // ---------------------------------------------------------------------------- | |
| 353 // | |
| 354 //####COPYRIGHTEND#### |