eLinux Development Environment --------------------------------------------------------- Please note that this document contains some links and references to internal Axis documentation and is in a "beta" state. Getting a Development Machine eLinux development is done on Linux using the ordinary CRIS Gnu tools. You can either use you personal Linux machine or use one of the common Linux servers administered by the systems department. Personal Machine Most developers who administers their personal Linux machines themselves use the RedHat distribution. The systems department use the Debian distribution on the machines they administer. If you want to install Debian yourself so that it will be supported by the systems department you should follow the Axis Debian Install Guide. Installation of the GNU Tools If you manage you own machine you need to install and update the CRIS GNU tools yourself, according to H-P's instructions. You may also want to read the section Accessing the Source Code below before proceeding. Note that you need to build and install the Gnu libc (glibc) headers and libraries also. The installation script takes care of this if the directories glibc (containing Gnu libc) and elinux-headers (containing the headers) are present. However, it requires some files that are created when the kernel is configured, so you need to do this first. Example (assuming that the kernel has been configured): % cvs -d ignucius:/home/cvsroot co -r latest-release cris-dist-all % cd cris-dist % ln -s `pwd`/../libs/glibc % ln -s `pwd`/../elinux/include elinux-headers % ./install-cris-tools The last step requires write access to the installation directory, so you may need to run it as root. The CRIS Gnu tools are normally installed in /usr/local/cris. Accessing the Source Code The source code for the tools and the eLinux system itself is version controlled using CVS. CVS is free software and is included in most Linux distributions. The manual is available in several formats, including info and HTML. Three different CVS repositories are used for eLinux related source code: cvs:/n/cvsroot Main repository with eLinux kernel, applications and libraries. It contains a number of modules: elinux (directory os/elinux) Kernel source code libs User mode libraries, including C libraries apps User mode applications tools Various tools products Product definitions install Makefile to do setup of the development environment ignucius:/home/cvsroot CRIS Gnu Tools (compiler, assembler, linker, etc.) pizza:/h/hendrikr/gdbcvsroot CRIS GDB (Gnu Debugger) To work with the source code you must check out a working copy. For performance reasons you should do this to a local file system. To see what changes have been made to the main repository you can use the Bonsai query interface and to look at the code itself using your web browser you can use the LXR Axis Cross-Reference. Setting up the Development Environment This section describes step by step how to set up the development environment: * Checking out a working copy of the source * Setting environment variables used by makefiles and tools * Building the eLinux specific tools * Build and install the boot loader A quick way to set up the development environment is to use the install/Makefile which does all of these steps, except the last one (since it is assumed that the boot loader should be installed setuid root). If you use this makefile you may skip the next three sections. Either check out the install directory from the main CVS repository or just get the makefile, and then run make elinux_tree. % cvs -d cvs:/n/cvsroot co install % cd install % make elinux_tree % source init_env You will still need to run the install-cris-tools script yourself, if you have not installed the CRIS Gnu tools already (or is using one of the common Linux servers). Checking Out a Working Copy of the Source Checkout the modules you need from the main CVS repository. If you want to build everything from source you will need all modules, possibly except install. Example: % cvs -d cvs:/n/cvsroot co elinux libs apps tools products Note that the eLinux kernel source is checked out into a directory elinux (not os/elinux) if you check out the module elinux. Environment Variables There are a number of environment variables you need to set, because they are used by the tools: export ELINUXDIR=path to your elinux checkout export ELIBSDIR=path to your libs checkout export APPS=path to your apps checkout export TOOLS=path to your tools checkout export EROOT=where to install ELINUX (target) builds export HROOT=where to install HOST builds (Assuming zsh/bash/ksh syntax) You also need to add the tools directory and the CRIS Gnu tools install directory (usually /usr/local/cris) to your path. The tool tools/init_env_elinux.pl creates a file called init_env in the current working directory, with the paths setup using the current working directory as base and adding elinux, libs, apps, tools, eroot and hroot. Source the file, using source init_env. This will make the shell read and execute the commands in the file in the current shell. You can put the content of the init_env file in your appropriate dot file or simply source the file when you want to work with eLinux. Having the environment variable definitions in a separate file makes it easy to work with several trees and switch between them. Example: % ./tools/init_env_elinux.pl % source init_env Building the eLinux Specific Tools You need to build the eLinux specific tools by running make in the tools directory. Example: % cd tools % make You also need to build the image decompressor from your elinux directory; make zImage. Boot Loader The normal way to boot the target system over the network is to use the Svinto boot loader (svinto_boot). You need to be root to run it, or install it locally and make it setuid root. The source code is available in the tools/e100boot directory in the main repository. Example (assuming you have checked out the tools directory from the main CVS repository): % cd tools/e100boot % make % su # make install % exit This will install the boot loader setuid root in the tools directory. Configuring the Kernel If you want to build the kernel you need a configuration which specifies the target hardware, which drivers to include, etc. This is done interactively by running make menuconfig in the elinux directory. Use the help button to get documentation about the different configuration options. Alternatively, you may just copy a suitable kernel configuration (file name kernelconfig) from the products directory tree, if there is one available for your hardware. Network configuration (IP and MAC addresses, routing information, etc.) were previously compiled into the kernel. However, this is no longer done unless the kernel configuration option CONFIG_KERNEL_IFCONFIG (General setup --> Use in-kernel ifconfig/route setup) is enabled. Instead the usual ifconfig and route commands are used to configure the network from user mode after booting. Building Applications To create a complete eLinux system you need a root file system which contains all the applications, scripts, configurations files and other things that should be included in the system. When building product releases the mkprod tool is used to ensure that the software configuration of the product is well defined. However, during development you may want to do this all manually. The rest of this section describes how to do this. The prefix $EROOT/ is used to denote files on the eLinux system to avoid confusing them with files on the host system. The makefiles for the libraries and applications are defined to make it easy to build either for the eLinux (target) system or the host system. You just need to do a make elinux or make host in the library or application directory (i.e. a subdirectory to libs or apps) to specify which kind of build you want to do next. Before you can build and application you need to build any libraries the application uses (apart from the Gnu C library which is built when installing the CRIS Gnu tools). This is done by executing make install in the library directory. When a make install is executed in an application directory the corresponding application is compiled, linked and installed in $EROOT/bin. Any configuration files the application needs will also be installed, typically in $EROOT/etc. . You need to create the rest of the directories and files you want (e.g. $EROOT/etc and $EROOT/proc) by hand. The elinux/user/root/etc directory contains some files you probably want to include. Also, you also need to create device files in $EROOT/dev. If your $EROOT is elinux/user/root you just need to run make gendevs in elinux/user to create standard device files. Note that the device files does not have to be real device files (which you have to be root to create). Instead you can use the mknod_elinux tool, located in elinux/scripts). This utility accepts the same options and arguments as the ordinary mknod(1), but instead of actually creating the special file it adds information about it (name, type, major and minor device number) to a file (romfs_meta.txt) which is used by the tool that generates ROM file system. Example of building a minimal system including the applications init, sash (simple shell), telnetd (a simple telnet daemon) and stfpd (a simple FTP deamon): % ln -s elinux/user/root eroot % (cd libs/uC-libc ; make install) # currently used by init % (cd libs/termcap ; make elinux ; make install) % (cd libs/readline ; make elinux ; make install) % (cd apps/init ; make elinux ; make install) % (cd apps/net-tools ; make elinux ; make install) % (cd apps/shell ; make elinux ; make install) % (cd apps/telnetd ; make elinux ; make install) % (cd apps/sftpd ; make elinux ; make install) % (cd elinux/user ; make gendevs) You should edit the $EROOT/etc/inittab file so that it includes the applications you want init to start. Before reading this file init will execute $EROOT/usr/rc.d/rc.init, which typically is a shell script which configures things like network addresses. Take a look at the files in products/camera/lisa/files/usr/rc.d to see how this can be done (but do not forget to change at least the MAC address, IP address and host name if you copy these files). Building the Kernel and ROM File System Running make (with default target) in the elinux directory will build the kernel, create a romfs image from the files in elinux/user/root (this is typically a symbolic link to the eroot directory which the EROOT environment variable specifies), and concatenate them together. The resulting file is called timage. If you have changed just the file system, make romfs will suffice. Building a Product For each product there is a file, prodspec, which specifies which applications, directories, libraries and special files should be included in the product. The tool mkprod performs the following actions: * Creates an eroot directory in the products directory. * Reads the configuration file. * Creates specified directories, symlinks and device files in the eroot tree. * Installes specified files (for instance boot scripts and web pages) from the files directory (in the product directory) to the eroot tree. * Checks out the specified libraries and applications, builds and installs them in the eroot tree. Note that some applications may need some manual preparation, like running a configure script beforehand. E.g the apps/ppp application needs some links to be created initially by running ./configure in its directory. When mkprod is done, the eroot directory should contain everything that product is configured to use. The mkprod tool currently does not configure and build the kernel, so you will have to do this by hand before running mkprod (using the configuration stored in the product directory). Example: % cd elinux % cp ../products/camera/lisa/kernelconfig .config % make menuconfig just save and exit % make -C user gendevs; make clean; make dep; make; make zImage % cd ../products/camera/lisa % mkprod -o This will create the products/camera/lisa/eroot tree with the Lisa product's applications and configuration files. The -o option to mkprod tells it to optimize the resulting tree for space. This is necessary when you need to put the resulting image in flash, but since it slows down building you usually want to skip it during developing. Booting the Target System The easiest way to network boot the target system is to use the boot_elinux tool (located in the tools directory). This script extracts some hardware register settings from the eLinux image and runs svinto_boot with these settings. It should be executed in the elinux directory. The kernel uses a serial port for console output, provided that the configuration option CONFIG_USE_SERIAL_CONSOLE (General setup --> Use serial console) is enabled (115200 baud, 8N1). Which serial port to use is selected with the configuration option CONFIG_DEBUG_PORT0 etc. (Hardware setup --> Serial-X). The boot loader may also print diagnostic messages a serial port. Which port to use is specified with the --bootfile command line argument to svinto_boot. The boot_elinux tool looks in the kernel configuration file and tells svinto_boot to use the configured debug port. Debugging Most applications can be debugged on the host using ordinary Linux tools. See tools/README.debug for some suggestions. The eLinux kernel can be debugged using GDB as described in the next section. Kernel Debugging with GDB The eLinux kernel includes a stub which may be used for cross-debugging of the kernel using GDB. Hendrik Ruijter has written an introduction to cross debugging with GDB. Follow his instruction to build and install GDB CRIS. On a Debian system you may alternatively use the binary installed with the Axis tools (/n/axis_src/TOOLS_REPOSITORY/current/gdb-cris). Note the same version of GDB CRIS is used for cross-debugging of eLinux (kernel only for now) as well as OSYS and eCos based systems. You need to configure the kernel (make menuconfig) with the configuration option CONFIG_KGDB (General setup --> Use kernel gdb debugger) enabled and do a make to rebuild the kernel. It will then be build with the GCC options -g (generate stabs debugging information) and -no-omit-frame-pointer (always use a frame pointer, which GDB CRIS needs to do stack backtraces). The debugging information will increase the size of the vmlinux file considerably, but not the size of the actual downloaded binary (except for the overhead of keeping a frame pointer...). When booting the kernel will immediately hit a compiled in breakpoint. From there you can set additional breakpoints, single step, examine variables and registers, etc. FAQ Q: I get permission denied using cvs or rsh. A: You need to have a .rhosts file, so that the machine where the repository resides will allow you to execute commands using rsh. Try creating a .rhosts file in your Axis-wide home directory, containing a single line with the name of the machine you are executing the cvs/rsh commands on. Note that a .rhost file is a potential security problem. If you are concerned about this you may want to use SSH instead (note that SSH is free only for non-commercial use...). If you have SSH installed you can set the environment variable CVS_RSH to ssh tell CVS to use it instead of rsh. Q: Backspace does not work when running make menuconfig. A: The machines administered by the systems department the default terminal settings are weird. Change them using stty(1) or use Ctrl-H for backspace. ------------------------------------------------------------------------ $Id: elinux_dev_env.html,v 1.4 2000/04/17 10:31:23 johana Exp $ $Log: elinux_dev_env.html,v $ Revision 1.4 2000/04/17 10:31:23 johana Corrected uC-libc, added a make zImage Revision 1.3 2000/04/17 09:57:24 petern Added information about explicit zImage installation and that some applications need manual configuration. Revision 1.2 2000/03/30 13:57:38 petern Corrected "lib" to "libs" in build example under Building Applications. Revision 1.1 2000/03/22 15:46:51 johana First in CVS on developer web