release/picobsd/doc/src/how2build.html

   1 <html>
   2 <! $FreeBSD: src/release/picobsd/doc/src/how2build.html,v 1.7.2.1 2000/11/07 23:36:45 joe Exp $ >
   3 <head>
   4 <title>PicoBSD Development Kit</title>
   5 </head>
   6 <body>
   7 <h1><center>            How to build your own version
   8                                 of PicoBSD?
   9 </center></h1>
  10
  11 <ol>
  12 <li>
  13 <p>     Beginning with version 0.4, PicoBSD sources are maintained as
  14         part of official FreeBSD CVS repository, so
  15         you can find them in src/release/picobsd.</p>
  16 </li>
  17 <li>
  18         Become root. You'll need to mount and unmount various volumes.
  19 </li>
  20 <li>
  21         Make sure you are running kernel with support for vn(4) devices.
  22         If you run plain GENERIC (just as it was installed on your system),
  23         you'll need to recompile you kernel and reinstall it. See the
  24         appropriate entries in The Handbook (/usr/share/doc/handbook).
  25 </li>
  26 <li>    Change working directory (<code>cd build</code>) and run the
  27         <code>./build</code> script. Select target language, size of MFS and
  28         one of pre-canned setups (personal dialup, dialin server or
  29         router-like). Details of each setup are contained in dial/,
  30         router/, isp/ and net/ directories respectively. You should at least
  31         check <code>${TYPE}/config/PICOBSD</code> file to make sure it contains
  32         the drivers you want.
  33
  34 <p>     You can also choose a special type called 'custom'. You'll need to
  35         supply the full path to your own custom config tree constructed
  36         exactly like one of the standard config directories. Also, you'll
  37         probably want to adjust the number of inodes on MFS - see the
  38         <code>stage1</code> script and look for <code>INODES=</code>.</p>
  39
  40 <p>     I also recommend to adjust the ISA devices parameters to
  41         match the ones of your hardware - though PicoBSD can save the
  42         changes from UserConfig, this way it will produce smaller
  43         <code>/kernel.config</code> file.</p>
  44 </li>
  45 <li>    I assume you will use 1.44MB floppy. If not, please edit the file
  46         <code>build/stage3</code>.
  47 </li>
  48 <li>    There are several directories which contain some sources and config
  49         files:
  50 <pre>
  51         build/                  main build directory; you MUST cd here!
  52         dial/                   config files for dialup setup
  53                 conf/           kernel config file
  54                 crunch1/        crunch of system programs
  55                 mfs.tree/       contains the MFS configuration
  56                 lang/           contains language-dependent files
  57                 floppy.tree/    contains the startup floppy hierarchy
  58
  59         isp/                    config files for dialin server setup
  60                 ...             (as above)
  61         net/                    config files for router-like setup
  62                 ...             (as above)
  63         tinyware/               collection of small system utilities
  64         tools/                  additional tools them needed during build
  65 </pre>
  66 <p>     There are no <code>/etc/passwd</code> nor <code>/etc/pwd.db</code>
  67         files on the "dial" floppy - in case of other types, they are
  68         reconstructed from <code>/etc/master.passwd</code> on each startup
  69         (and then put on MFS with the rest of <code>/etc</code>).
  70         In case of "dial" type floppy, you don't need them at all.</p>
  71
  72 <p>     NOTE: thanks to the above, the floppy is needed only during startup,
  73         and then only if you want to synchronize (possibly changed) MFS /etc
  74         with the one on the floppy. It means that you can pull off the floppy
  75         from the drive as soon as <code>login:</code> prompt appears.
  76         In other words, it is almost equal to read-only floppy.</p>
  77 </li>
  78 <li>    Edit the set of installed programs.
  79 <ul>
  80 <li>            Go to <code>${TYPE}/crunch1</code> directory, and edit it
  81                 to suit your needs. Keep in mind that floppies aren't made
  82                 of rubber... :-)
  83 </li>
  84 <li>            There are some patches included in these directories, which
  85                 are applied during build process to some of the Makefiles in
  86                 your <code>/usr/src</code>. These patches attempt to decrease
  87                 the size of some programs by cutting off rarely/unlikely used
  88                 parts. The patches are reversed when you do a
  89                 <code>make clean</code> (or <code>build/clean</code>
  90                 for that matter).
  91 <p>             NOTE: patches may fail to apply, if your sources are too
  92                 different from the ones I used. Don't worry: they are so
  93                 straightforward that you can apply them by hand.</p>
  94 </li>
  95 <li>            In order to have a functioning system you MUST include at
  96                 least <code>/stand/init</code>, or <code>/stand/oinit</code>,
  97                  or <code>/stand/sysinstall</code> in
  98                 your <code>crunch.conf</code>. Of course these can be your
  99                 own programs... But if you install the stock
 100                 <code>/sbin/init</code>, you
 101                 also have to install some others, like sh, getty, login etc...
 102 <p>             This release of PicoBSD contains a small replacement for
 103                 init(8), called 'oinit'. You can find it in TinyWare
 104                 collection. The main building script allows you to use it
 105                 instead of normal init(8). <b>Be sure to read the oinit's docs
 106                 before you decide to use it!</b></p>
 107 </li>
 108 </ul>
 109 </li>
 110 <li>    Make sure that the system you're running has /dev/[r]vn0* entries in
 111         /dev directory (if not, you can make them with 'MAKEDEV vn0'), AND
 112         that your running kernel has built-in vnode driver (there should be a
 113         line in your kernel config file stating 'pseudo-device vn xxx').
 114 </li>
 115 <li>    You'll need at least 9MB of free disk space, and free /mnt directory.
 116 </li>
 117 <li>    Do a <code>cd build/</code> and fire off the <code>./build</code>
 118         script. Select the build parameters or 'n' for 'no change'. If all
 119         is well, after some time (like 10-30m) you end up with a
 120         'picobsd.bin' file in this directory.
 121
 122 <p>     WARNING: make sure you don't have stale <code>.depend</code> files
 123         around!!! You may encounter many strange errors during build process
 124         in that case.</p>
 125
 126 <p>     If there were any errors, please execute each script by hand and try
 127         to find what causes this error. Most often this will be one of the
 128         following reasons:</p>
 129 <ul>
 130 <li>            <code>crunchgen</code> can't find the source directory for a
 131                 program 'proggy':
 132 <ul>
 133 <li>            make sure that the source directory for 'proggy' is called
 134                   'proggy', otherwise the crunchgen won't find it
 135 </li>
 136 <li>            make sure that the Makefile allows crunchgen to deduce the
 137                   set of objects to build. You can manually add an OBJS= ...
 138                   to the program's Makefile.
 139 </li>
 140 </ul>
 141 </li>
 142 <li>            crunch fails to build.
 143 <ul>
 144 <li>            check your system source tree for stale .depend files and/or
 145                   objects (*.o)
 146 </li>
 147 <li>            see if the individual programs can be built using original
 148                   Makefiles. If not, cvsup the correct sources.
 149 </li>
 150 </ul>
 151 </li>
 152 <li>            /: write failed - file system is full
 153 <ul>
 154 <li>            this one is obvious - you wanted to put too many programs on
 155                 the MFS and/or the target floppy. Or, you really don't have
 156                 any space left on the root partition.. :-)
 157 </li>
 158 <li>            also, you can check if the
 159                 MFS size is correctly reported while it's still mounted (right
 160                 after <code>stage1</code> script ends).
 161 </li>
 162 </ul>
 163 <li>            the build process displays "Preparing MFS" and then
 164                 silently stops. In this case check if you're running it as
 165                 root, and that you run kernel with support for vn(4)
 166                 devices. Also, you can add 'set -x' at hte beginning
 167                 of the scripts to see exactly where they stop.
 168 </li>
 169 </ul>
 170
 171         You can also remove <code>2>&amp;1</code> redirections from Makefiles
 172         to see the stderr.
 173 </li>
 174 <li>    Transfer this file to the floppy:
 175 <pre>
 176                 dd if=picobsd.bin of=/dev/rfd0
 177 </pre>
 178
 179         (The 'build' script asks you if you want to do this.)
 180 </li>
 181 </ol>
 182
 183 <p>That's all. You're welcome to change and improve these scripts. If you
 184  stumble upon something which looks like a good idea to have it here, let me
 185  know.</p>
 186
 187 <p>If, for some reason, the scripts don't work for you at all, also let me
 188  know.</p>
 189
 190 <hr>
 191 <i>Last modified:
 192 @DATE@
 193
 194 <p><A HREF="mailto:abial@freebsd.org">&lt;abial@freebsd.org&gt;</a></i></p>
 195 </body>
 196 </html>