doc/html/user-guide/editing-the-sources.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Editing the Sources</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos User Guide"
  20 HREF="ecos-user-guide.html"><LINK
  21 REL="UP"
  22 TITLE="Manual Configuration"
  23 HREF="manual-configuration.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Editing an eCos Savefile"
  26 HREF="editing-an-ecos-savefile.html"><LINK
  27 REL="NEXT"
  28 TITLE="Modifying the Memory Layout"
  29 HREF="modifying-the-memory-layout.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos User Guide</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="editing-an-ecos-savefile.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 28. Manual Configuration</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="modifying-the-memory-layout.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="EDITING-THE-SOURCES">Editing the Sources</H1
  86 ><P
  87 >For many users, controlling the packages and
  88           manipulating the available configuration options will be
  89           sufficient to create an embedded operating system that meets
  90           the application's requirements. However, since <SPAN
  91 CLASS="PRODUCTNAME"
  92 >eCos</SPAN
  93 > is
  94           shipped entirely in source form, it is possible to go
  95           further when necessary: you can edit the <SPAN
  96 CLASS="PRODUCTNAME"
  97 >eCos</SPAN
  98 > sources themselves. This requires some
  99           understanding of the way the <SPAN
 100 CLASS="PRODUCTNAME"
 101 >eCos</SPAN
 102 > build system works.
 103         </P
 104 ><P
 105 >The most obvious place to edit the source code is directly
 106 in the component repository. For example, you could
 107 edit the file <TT
 108 CLASS="FILENAME"
 109 >kernel/<TT
 110 CLASS="REPLACEABLE"
 111 ><I
 112 >&#60;version&#62;</I
 113 ></TT
 114 >/src/sync/mutex.cxx</TT
 115 >
 116 to change the way kernel mutexes work, or possibly just to add some
 117 extra diagnostics or assertions. Once the file has been edited,
 118 it is possible to invoke <B
 119 CLASS="COMMAND"
 120 >make</B
 121 > at
 122 the top level of the build tree and the target library will be rebuilt
 123 as required. A small optimization is possible: the build tree is
 124 largely a mirror of the component repository, so it too will contain
 125 a subdirectory <TT
 126 CLASS="FILENAME"
 127 >kernel/<TT
 128 CLASS="REPLACEABLE"
 129 ><I
 130 >&#60;version&#62;</I
 131 ></TT
 132 ></TT
 133 >;
 134 if make is invoked in this directory
 135 then it will only check for changes to the kernel sources, which
 136 is a bit more efficient than checking for changes throughout the component
 137 repository. </P
 138 ><P
 139 >Editing a file in the component repository is fine if this
 140 tree is used for only one <SPAN
 141 CLASS="PRODUCTNAME"
 142 >eCos</SPAN
 143 > configuration. If the repository
 144 is used for several different configurations, however, and especially
 145 if it is shared by multiple users, then making what may be experimental
 146 changes to the master sources would be a bad idea. The build system provides
 147 an alternative. It is possible to make a copy of the file in the
 148 build tree, in other words copy <TT
 149 CLASS="FILENAME"
 150 >mutex.cxx</TT
 151 > from
 152 the <TT
 153 CLASS="FILENAME"
 154 >kernel/<TT
 155 CLASS="REPLACEABLE"
 156 ><I
 157 >&#60;version&#62;</I
 158 ></TT
 159 >/src/sync</TT
 160 > directory
 161 in the component repository to <TT
 162 CLASS="FILENAME"
 163 >kernel/<TT
 164 CLASS="REPLACEABLE"
 165 ><I
 166 >&#60;version&#62;</I
 167 ></TT
 168 >/src/sync</TT
 169 > in
 170 the build tree, and edit the file in the build tree. When <B
 171 CLASS="COMMAND"
 172 >make</B
 173 > is
 174 invoked it will pick up local copies of any of the sources in preference
 175 to the master versions in the component repository. Once you have
 176 finished modifying the <SPAN
 177 CLASS="PRODUCTNAME"
 178 >eCos</SPAN
 179 > sources you can install the final version
 180 back in the component repository. If the changes were temporary
 181 in nature and only served to aid the debugging process, then you
 182 can discard the modified version of the sources. </P
 183 ><P
 184 >The situation is slightly more complicated for the header
 185 files that a package may export, such as the C library&#8217;s <TT
 186 CLASS="FILENAME"
 187 >stdio.h</TT
 188 > header
 189 file, which can be found in the directory <TT
 190 CLASS="FILENAME"
 191 >language/c/libc/<TT
 192 CLASS="REPLACEABLE"
 193 ><I
 194 >&#60;version&#62;</I
 195 ></TT
 196 >/include</TT
 197 >.
 198 If such a header file is changed, either directly in the component
 199 repository or after copying it to the build tree, then <B
 200 CLASS="COMMAND"
 201 >make</B
 202 > must
 203 be invoked at the top level of the build tree. In cases like this
 204 it is not safe to rebuild just the C library because other packages
 205 may depend on the contents of <TT
 206 CLASS="FILENAME"
 207 >stdio.h</TT
 208 >. </P
 209 ></DIV
 210 ><DIV
 211 CLASS="NAVFOOTER"
 212 ><HR
 213 ALIGN="LEFT"
 214 WIDTH="100%"><TABLE
 215 SUMMARY="Footer navigation table"
 216 WIDTH="100%"
 217 BORDER="0"
 218 CELLPADDING="0"
 219 CELLSPACING="0"
 220 ><TR
 221 ><TD
 222 WIDTH="33%"
 223 ALIGN="left"
 224 VALIGN="top"
 225 ><A
 226 HREF="editing-an-ecos-savefile.html"
 227 ACCESSKEY="P"
 228 >Prev</A
 229 ></TD
 230 ><TD
 231 WIDTH="34%"
 232 ALIGN="center"
 233 VALIGN="top"
 234 ><A
 235 HREF="ecos-user-guide.html"
 236 ACCESSKEY="H"
 237 >Home</A
 238 ></TD
 239 ><TD
 240 WIDTH="33%"
 241 ALIGN="right"
 242 VALIGN="top"
 243 ><A
 244 HREF="modifying-the-memory-layout.html"
 245 ACCESSKEY="N"
 246 >Next</A
 247 ></TD
 248 ></TR
 249 ><TR
 250 ><TD
 251 WIDTH="33%"
 252 ALIGN="left"
 253 VALIGN="top"
 254 >Editing an <SPAN
 255 CLASS="PRODUCTNAME"
 256 >eCos</SPAN
 257 > Savefile</TD
 258 ><TD
 259 WIDTH="34%"
 260 ALIGN="center"
 261 VALIGN="top"
 262 ><A
 263 HREF="manual-configuration.html"
 264 ACCESSKEY="U"
 265 >Up</A
 266 ></TD
 267 ><TD
 268 WIDTH="33%"
 269 ALIGN="right"
 270 VALIGN="top"
 271 >Modifying the Memory Layout</TD
 272 ></TR
 273 ></TABLE
 274 ></DIV
 275 ></BODY
 276 ></HTML
 277 >