README

   1
   2 uClinux/distribution
   3 ====================
   4
   5 Contents
   6 --------
   7
   8 0) Introduction
   9 1) Instructions for compiling
  10 2) Changing the applications/kernel-options/libraries
  11 3) Documentation
  12
  13
  14 0) Introduction
  15 ---------------
  16
  17 The uClinux-dist source package is an "all-in-one" build framework for
  18 generating a complete system. It has been developed with embedded devices
  19 in mind, but it can just as equally be used for normal computing devices
  20 (like a PC for example). It is ideal for building small, light weigth
  21 systems.
  22
  23 The uClinux-dist was originally targeted specifically at non-MMU
  24 microprocessors. But for many years now it has supported full VM processors.
  25 It supports a wide varity of hardware, many CPUs and  a large number of
  26 target boards.
  27
  28
  29 1) Instructions for Compiling
  30 -----------------------------
  31
  32   1. You will need a cross-compiler package for your target. Many binary
  33      tool packages exists specifically for compiling uClinux. Install
  34      that in the standard way first. For example, if you are targeting m68k
  35      or ColdFire systems then you can use the m68k-uclinux-tools binary
  36      packages of www.uclinux.org.
  37
  38   2. If you have not un-archived the source package then do that now.
  39      It is a gziped tar image, so do:
  40
  41        tar xvzf uClinux-dist-XXXXXXXX.tar.gz
  42
  43      This will dump the source into a "uClinux-dist" directory.
  44      You can do this into any directory, typically use your own user
  45      login. (I don't recommend devloping as root, it is a bad pactice,
  46      and it will bite you one day!)
  47
  48   3. Cd into the source tree:
  49
  50           cd uClinux-dist
  51
  52   4. Configure the build target:
  53
  54           make xconfig
  55
  56      You can also use "make config" or "make menuconfig" if you prefer.
  57
  58      The top level selection is straight forward if you know the vendor of
  59      the board you want to compile for. You can choose also to modify the
  60      underlying default kernel and application configuration if you want.
  61
  62      At first it is suggested that you use the default configuration for
  63      your target board. It will almost certainly work "as is".
  64
  65      You can also select between different kernel versions and libraries,
  66      at this top level. Not all kernel versions support all boards, as a
  67      general rule choose 3.x. uClibc is the perferred library choice on
  68      all targets (both MMU-less and VM processors). If you choose a
  69      combination that doesn't have a default configuration file then the
  70      config step will issue a message letting you know.
  71
  72      Based on what platform you choose in this step the build will generate
  73      an appropriate default application set.
  74
  75      Sometimes a number of questions will appear after you 'Save and Exit'.
  76      Do not be concerned, it just means that some new config options have
  77      been added to the source tree that do not have defaults for the
  78      configuration you have chosen.  If this happens the safest option is
  79      to answer 'N' to each question as they appear.
  80
  81   5. Build the dependencies (if required):
  82
  83           make dep
  84
  85      If you selected the 3.x kernel then you do not need to do this step.
  86      If you choose the 2.4.x kernel you must run the make dep.
  87
  88   6. Build the image:
  89
  90           make
  91
  92
  93   Thats it!
  94
  95   The make will generate appropriate binary images for the target hardware
  96   specified. All generated files will be placed under the "images" directory.
  97   The exact files vary from target to target, typically you end up with
  98   something like an "image.bin" file.
  99
 100   How to load and run the generated image will depend on your target system
 101   hardware. There are a number of HOWTO documents under the Documentation
 102   directy that describe how to load and run the image on specific boards.
 103   Look for a file named after your target board.
 104
 105
 106 2) Changing the Applications/Kernel/Libraries
 107 ---------------------------------------------
 108
 109   You can modify the kernel configuration and application set generated for
 110   your target using the config system. You can configure by running one of
 111   the following three commands:
 112
 113         make xconfig       - graphical X11 based config
 114         make menuconfig    - text menu based config
 115         make config        - plain text shell script based config
 116
 117   Menuconfig and xconfig are the simplest, I would recommend using one of
 118   them.
 119
 120   The key options under the "Target Platform Selection" menu are the
 121   following:
 122
 123         Customize Kernel Settings
 124             Selecting this option run the standard Linux kernel config.
 125
 126         Customize Vendor/User Settings
 127             Selecting this option will run a configure process allowing
 128             you to enable or disable individual applications and libraries.
 129
 130    Use the online "Help" if unsure of what a configuration option means.
 131
 132    When you 'Save and Exit' the build system will run you through the
 133    configs you have selected to customise.
 134
 135
 136 3) Documention
 137 --------------
 138
 139   There is an assortment of documentaion files under the Documentaion
 140   directory. The more interresting ones are:
 141
 142        SOURCE  -- file at the top level gives a brief run down of the
 143                   structure of this source distribution package.
 144
 145        Documentation/Adding-User-Apps-HOWTO
 146                -- description of how to add a new application into the
 147                   config and build setup of the distribution.
 148
 149        Documentation/Adding-Platforms-HOWTO
 150                -- description of how to add a new vendor board config to
 151                   the distribution.
 152
 153        Documentation/<BOARD>-HOWTO
 154                -- describes building and loading for a particular board.
 155