flash_v2: README.host comparison

comparison README.host @ 290:3ecf91f6663a

Update instructions for building the host-side software

author	bartv
date	Tue, 13 Aug 2002 20:10:16 +0000
parents
children	3f4258400ba5

comparison

equal deleted inserted replaced

-:bd1db6a90df9
+:3ecf91f6663a
+		eCos Host-side Software
+		=======================
+This README file only describes the eCos host-side software. For
+details of the eCos target-side software or the required toolchains,
+please see other documentation. A good starting point is
+http://sources.redhat.com/ecos
+There are two categories of host-side software. The host subdirectory
+contains generic software, primarily related to the eCos configuration
+technology. All eCos users will need to use some of this technology to
+configure and build eCos, either using pre-built binaries or by
+building the host-side software from source. The generic software
+should be portable to a wide range of host platforms.
+There is also package-specific host-side software. Much of this is I/O
+related. For example the generic USB-slave package contains some
+programs related to testing; a test application is run on a target
+with suitable USB slave-side hardware, and needs to interact with
+another program running on the USB host; the latter is
+package-specific host-side software and can be found in the
+subdirectory packages/io/usb/slave. Code like this may have
+significant platform dependencies and may only work on a single
+platform or on a small number of platforms. There may also be
+special requirements, for example it may be necessary to install some
+programs suid root so that they have appropriate access to the
+hardware.
+The host subdirectory includes the following:
+infra/
+This is an implementation of the eCos infrastructure that can be
+used on the host-side, and provides assertion, tracing and
+testcase support.
+NOTE: the eCos infrastructure facilities are not especially
+well-suited to host-side development, in particular they are not
+C++-oriented. There are plans to remove the current infrastructure
+completely and replace it with something more suitable. People
+planning new projects should be aware of this, and may wish to
+avoid using the current infrastructure.
+libcdl/
+The CDL library lies at the heart of the eCos configuration
+technology.
+tools/configtool/
+The sources to the various configuration tools can be found here.
+tools/configtool/common/common/
+Contains sources related to makefile generation, shared by the
+command line and graphical tools.
+tools/configtool/standalone/common/
+Contains the command line ecosconfig tool.
+tools/configtool/standalone/wxwin/
+Contains sources for the wxWindows-based, Linux and Windows graphical
+configuration tool. The Windows version can currently only be
+built with Visual C++, not with cygwin g++.
+tools/configtool/common/win32/
+tools/configtool/standalone/win32/
+Contains sources for the older, MFC-based, Windows-only graphical
+configuration tool. Again this can currently only be built with
+Visual C++.
+The two graphical configuration tools have their own build procedures,
+described in tools/configtool/standalone/wxwin/ReadMe and
+tools/configtool/standalone/win32/ReadMe respectively.
+Package-specific host-side code lives in the host subdirectory of the
+appropriate package, for example packages/io/usb/slave/<version>/host.
+Most packages only provide target-side code and hence will not have a
+host subdirectory. Users can install various packages from a variety
+of sources, and where a package does have host-side software the
+package documentation should be consulted for further information.
+Installing on Linux and Other Unix Systems
+------------------------------------------
+Both generic host-side software (infra, libcdl and ecosconfig) and
+package-specific software can be built with the conventional
+"configure/make/make install" sequence. However the code does not
+conform fully to GNU coding standards so some operations such as "make
+dist" are not supported. There is limited support for DejaGnu-based
+testing.
+Much of the host-side software has a dependency on Tcl. This is not
+supplied with the sources since many users will already have a
+suitable installation, for example it is shipped as standard with
+all major Linux distributions. Any release of Tcl from 8.0 onwards
+should  be usable.
+There are two main approaches to building the host-side software:
+1) build the generic and the package-specific code in one build tree.
+This uses the top-level configure script. The script automatically
+invokes the configure script in the main host subdirectory. In
+addition it searches the packages hierarchy for host subdirectories
+containing their own configure scripts and will invoke those.
+Note: the search for host subdirectories happens during configure
+time, not during the make. If new packages with host-side code are
+added to the repository then it will be necessary to re-run the
+toplevel configure script.
+2) build the generic code in one build tree, using the configure
+script in the toplevel's host subdirectory. Then build some or all
+of the package-specific code in separate build trees, using the
+configure scripts in each package's host subdirectory.
+The first approach is generally simpler. However some of the
+package-specific code requires special installation, for example a
+program may have to be installed suid root so that it has the right
+privileges to access hardware, and hence the "make install" step has
+to be run by the superuser. Also some of the package-specific code is
+rather specialized and may be of no interest to many users. For
+example, the USB testing code is only useful when developing
+USB-based applications. Hence some users may prefer the second
+approach, building just the generic code and a subset of the
+package-specific code.
+It is necessary to use a separate build tree rather than build
+directly in the source tree. This is enforced by the configure scripts.
+$ mkdir build
+$ cd build
+The next step is to run the desired configure script. To build all
+the host-side software this means the toplevel configure script:
+$ <path>/configure <args>
+Alternatively to build just the generic host-side software, use the
+configure script in the host subdirectory.
+$ mkdir host
+$ cd host
+$ <path>/host/configure <args>
+Or, to build just one package's host-side code:
+$ mkdir -p packages/io/usb/slave/current/host
+$ cd packages/io/usb/slave/current/host
+$ <path>/packages/io/usb/slave/current/host/configure <args>
+(It is not actually necessary to use the same directory structure in
+the build tree as in the source tree, but doing so can avoid
+confusion).
+A list of all the command-line options can be obtained by running
+"configure --help". The most important ones are as follows:
+1) --prefix. This can be used to specify the location of the install
+tree, defaulting to /usr/local, so the ecosconfig program ends up
+in /usr/local/bin/ecosconfig and the CDL library ends up in
+/usr/local/lib/libcdl.a. If an alternative location is preferred
+this can be specified with --prefix, for example:
+$ <path>/configure --prefix=/usr/local/ecos <args>
+2) --enable-debug. By default all assertions and tracing are disabled.
+When debugging any of the generic host-side software these should
+be enabled. Some package-specific code may not have any extra
+debug support, in which case --enable-debug would be ignored.
+$ <path>/configure --enable-debug
+It is also possible to control most of the assertion and tracing
+macros at a finer grain. This is intended mainly for use by the
+developers.
+--disable-asserts        disable all assertions
+--disable-preconditions  disable a subset of the assertions
+--disable-postconditions disable a subset of the assertions
+--disable-invariants     disable a subset of the assertions
+--disable-loopinvariants disable a subset of the assertions
+--disable-tracing        disable tracing
+--disable-fntracing      disable function entry/exit tracing
+3) --with-tcl=<path>
+--with-tcl-header=<path>
+--with-tcl-lib=<path>
+--with-tcl-version=<number>
+The host-side tools have a dependency on Tcl, which is not supplied
+with the sources because many people will already have a suitable
+installation. Specifically it is necessary to have the header file
+tcl.h and appropriate libraries such that -ltcl will work - this
+can involve either static or shared libraries.
+By default the configure script will assume that there is a
+suitable Tcl installation in the install location, so if there is
+no --prefix argument then it will look for /usr/local/include/tcl.h
+and it will add -L/usr/local/lib to the library search path. If
+Tcl is installed elsewhere then this can be specified with a
+--with-tcl option. For example, if the default installation in
+/usr should be used then the following configure option is
+appropriate:
+$ <path>/configure --with-tcl=/usr <args>
+If the Tcl libraries and Tcl headers are installed in different
+locations, such as when a separate --prefix and --exec-prefix are
+used, the --with-tcl-header and --with-tcl-lib options can be used
+to specify both location. The configure script will expect to find
+<tcl-header-dir>/include/tcl.h and <tcl-lib-dir>/lib/tclConfig.sh.
+The --with-tcl option has precedence and if used will override the
+--with-tcl-header and --with-tcl-lib options.
+It is possible to have multiple versions of Tcl installed, for
+example libtcl8.0.a, libtcl8.1.a, and so on. Typically linking with
+-ltcl will result in the latest version being used. It is possible
+to specify a different version using --with-tcl-version, e.g.:
+$ <path>configure --with-tcl=/usr/local/scriptics --with-tcl-version=8.1 <args>
+Following the configure step the build tree should be set up
+correctly. All that remains is the actual build and install:
+$ make
+$ make install
+This should result in an ecosconfig executable, plus appropriate
+libraries and header files. If the install prefix is a system
+location, for example /usr/local/, then "make install" will normally
+require root privileges. Also some of the package-specific software
+has special installation requirements, for example programs that need
+to be installed suid root, and this will also need root privileges.
+Installing under Cygwin
+-----------------------
+Installing under cygwin requires essentially the same steps as
+under Linux. It is more likely that a suitable --prefix option will
+have to be used, and that the location of the Tcl installation needs
+to be specified with --with-tcl. However appropriate use of cygwin
+mount points may avoid some of these problems. If the full path to
+the configure script contains spaces, then the short form of the path
+should be used when invoking configure.
+One issue to be aware of is the naming convention for the Tcl library.
+On a Unix system this will typically be called libtcl8.3.a (adjusted
+according to the version number), with a symbolic link from libtcl.a
+to the most recent version. Under cygwin the equivalent library is
+called libtcl80.a, and symbolic links are not used. For a standard
+cygwin installation the configure script knows how to pick up the
+appropriate library, but if a more recent version of Tcl has been
+installed then due care has to be taken with the --with-tcl-version
+option.
+Installing with Visual C++
+--------------------------
+Under Windows it is possible to build the generic host-side software
+(infra, libcdl and ecosconfig) with Visual C++ but this is deprecated.
+Building with g++ under cygwin is preferred.
+It is still necessary to run the configure script and a suitable make
+utility. That requires a shell and a Unix-like environment, as
+provided by cygwin. The Visual C++ compiler cl.exe needs to be on the
+shell's search path, and some environment variables such as INCLUDE
+and LIB may need to be set to point at the Visual C++ installation -
+the details may vary depending on the version of the compiler. Then
+the configure command should be run like this:
+$ CC=cl CXX=cl <path>/host/configure <args>
+Note that the path should be a cygwin path: cygwin mount points are
+accepted and forward slashes should be used. The various configure
+scripts now detect that Visual C++ should be used, and adapt
+accordingly.
+Depending on what cygwin mount points are set up, /usr/local may or
+may not be an appropriate install location for VC++ applications.
+If not, the install location should be specified with --prefix:
+$ CC=cl CXX=cl <path>/configure --prefix=<install-path> <args>
+It is also necessary to use the right version of Tcl. For a VC++ build
+the cygwin release of Tcl should not be used. Instead a suitable
+prebuilt Tcl package can be obtained from http://www.scriptics.com/.
+It is necessary to tell the configure script where this has been
+installed, for example:
+$ CC=cl CXX=cl <path>/configure --prefix=<install-path> \
+--with-tcl=/cygdrive/d/local/scriptics/Tcl/tcl8.1 <args>
+The library name will be of the form tcl81.lib, and there will not be
+a symbolic link from tcl.lib to the appropriate version. It will be
+necessary to specify the Tcl version explicitly since the default
+version is currently 8.0.
+$ CC=cl CXX=cl <path>/configure --prefix=<install-path> \
+--with-tcl=/d/local/scriptics/Tcl/tcl8.1 --with-tcl-version=81 <args>
+Following a successful configure, the tools can be built and installed
+in the normal fashion:
+$ make
+$ make install
+More Information
+================
+Please see the eCos web site, http://sources.redhat.com/ecos/, for
+further details. This includes the FAQ, a form for reporting problems,
+and details of the various mailing lists
+(http://sources.redhat.com/ecos/intouch.html) At the time of writing
+there are no separate mailing lists for the eCos host-side sources,
+the main mailing list ecos-discuss@sources.redhat.com should be used
+instead.
+//####COPYRIGHTBEGIN####
+//
+//----------------------------------------------------------------------------
+// Copyright (C) 2002 Bart Veer
+// Copyright (C) 2000, 2001 Red Hat, Inc.
+//
+// This file is part of the eCos host tools.
+//
+// This program is free software; you can redistribute it and/or modify it
+// under the terms of the GNU General Public License as published by the Free
+// Software Foundation; either version 2 of the License, or (at your option)
+// any later version.
+//
+// This program is distributed in the hope that it will be useful, but WITHOUT
+// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+// FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+// more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// this program; if not, write to the Free Software Foundation, Inc.,
+// 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+//
+// ----------------------------------------------------------------------------
+//
+//####COPYRIGHTEND####

Mercurial > flash_v2

comparison README.host @ 290:3ecf91f6663a