doc/html/user-guide/creating-build-tree.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 >Creating the Build Tree</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="Manual Configuration"
  26 HREF="manual-configuration.html"><LINK
  27 REL="NEXT"
  28 TITLE="Conflicts and constraints"
  29 HREF="conflicts-and-constraints.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="manual-configuration.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="conflicts-and-constraints.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="CREATING-BUILD-TREE">Creating the Build Tree</H1
  86 ><P
  87 >Generating a build tree is a non-trivial operation and
  88           should not be attempted manually. Instead, <SPAN
  89 CLASS="PRODUCTNAME"
  90 >eCos</SPAN
  91 > is shipped
  92           with a tool called <B
  93 CLASS="COMMAND"
  94 >ecosconfig</B
  95 > that should
  96           be used to create a build tree.</P
  97 ><P
  98 >Usually <B
  99 CLASS="COMMAND"
 100 >ecosconfig</B
 101 > will be
 102 run inside the build tree itself. If you are creating a new build
 103 tree then typically you will create a new empty directory using
 104 the <B
 105 CLASS="COMMAND"
 106 >mkdir</B
 107 > command, <B
 108 CLASS="COMMAND"
 109 >cd</B
 110 > into
 111 that directory, and then invoke <B
 112 CLASS="COMMAND"
 113 >ecosconfig</B
 114 > to
 115 create a configuration. By default, the configuration is stored
 116 in a file <TT
 117 CLASS="FILENAME"
 118 >ecos.ecc</TT
 119 > in the current
 120 directory. The configuration may be modified by editing this file directly. <B
 121 CLASS="COMMAND"
 122 >ecosconfig</B
 123 > itself
 124 deals with a number of coarse-grained configuration options such
 125 as the target platform and the packages that should be used.</P
 126 ><P
 127 >The <B
 128 CLASS="COMMAND"
 129 >ecosconfig</B
 130 > tool is also
 131 used subsequently to generate a build tree for a configuration.
 132 Once a build tree exists, it is possible to run <B
 133 CLASS="COMMAND"
 134 >ecosconfig</B
 135 > again
 136 inside the same build tree. This will be necessary if your wish
 137 to change some of the configuration options.</P
 138 ><P
 139 ><B
 140 CLASS="COMMAND"
 141 >ecosconfig</B
 142 > does not generate
 143 the top-level directory of the build tree; you must do this
 144         yourself. </P
 145 ><TABLE
 146 BORDER="5"
 147 BGCOLOR="#E0E0F0"
 148 WIDTH="70%"
 149 ><TR
 150 ><TD
 151 ><PRE
 152 CLASS="SCREEN"
 153 >$ mkdir ecos-work
 154 $ cd ecos-work</PRE
 155 ></TD
 156 ></TR
 157 ></TABLE
 158 ><P
 159 >The next step is to run <B
 160 CLASS="COMMAND"
 161 >ecosconfig</B
 162 >: </P
 163 ><TABLE
 164 BORDER="5"
 165 BGCOLOR="#E0E0F0"
 166 WIDTH="70%"
 167 ><TR
 168 ><TD
 169 ><PRE
 170 CLASS="SCREEN"
 171 >$ ecosconfig &lt;qualifiers&gt; &lt;command&gt;</PRE
 172 ></TD
 173 ></TR
 174 ></TABLE
 175 ><DIV
 176 CLASS="SECT2"
 177 ><H2
 178 CLASS="SECT2"
 179 ><A
 180 NAME="AEN2416">ecosconfig qualifiers</H2
 181 ><P
 182 >The available command line qualifiers for
 183             <B
 184 CLASS="COMMAND"
 185 >ecosconfig</B
 186 > are as follows. Multiple
 187             qualifiers may be used on the command line:
 188           </P
 189 ><P
 190 ></P
 191 ><DIV
 192 CLASS="VARIABLELIST"
 193 ><DL
 194 ><DT
 195 ><TT
 196 CLASS="OPTION"
 197 >--help</TT
 198 ></DT
 199 ><DD
 200 ><P
 201 >Provides basic usage guidelines for the
 202               available commands and qualifiers.</P
 203 ></DD
 204 ><DT
 205 ><TT
 206 CLASS="OPTION"
 207 >--config=&lt;file&gt;</TT
 208 ></DT
 209 ><DD
 210 ><P
 211 >Specifies an <SPAN
 212 CLASS="PRODUCTNAME"
 213 >eCos</SPAN
 214 > configuration save file for
 215                   use by the tool. By default, the file
 216                   <TT
 217 CLASS="FILENAME"
 218 >ecos.ecc</TT
 219 > in the
 220                   current directory is used. Developers may prefer to
 221                   use a common location for all their <SPAN
 222 CLASS="PRODUCTNAME"
 223 >eCos</SPAN
 224 >
 225                   configurations rather than keep the configuration
 226                   information in the base of the build tree.</P
 227 ></DD
 228 ><DT
 229 ><TT
 230 CLASS="OPTION"
 231 >--prefix=&lt;dir&gt;</TT
 232 ></DT
 233 ><DD
 234 ><P
 235 >Specifies an alternative location for the
 236                   install tree. By default, the install tree resides
 237                   inside the <TT
 238 CLASS="FILENAME"
 239 >install</TT
 240 >
 241                   directory in the build tree. Developers may prefer
 242                   to locate the build tree in a temporary file
 243                   hierarchy but keep the install tree in a more
 244                   permanent location.</P
 245 ></DD
 246 ><DT
 247 ><TT
 248 CLASS="OPTION"
 249 >--srcdir=&lt;dir&gt;</TT
 250 ></DT
 251 ><DD
 252 ><P
 253 >Specifies the location of the component
 254                   repository. By default, the tool uses the location
 255                   specified in the
 256                   <TT
 257 CLASS="REPLACEABLE"
 258 ><I
 259 >ECOS_REPOSITORY</I
 260 ></TT
 261 >
 262                   environment variable. Developers may prefer to use
 263                   of this qualifier if they are working with more than
 264                   one repository.</P
 265 ></DD
 266 ><DT
 267 ><TT
 268 CLASS="OPTION"
 269 >--no-resolve</TT
 270 ></DT
 271 ><DD
 272 ><P
 273 >Disables the implicit resolution of conflicts
 274                   while manipulating the configuration data.
 275                   developers may prefer to resolve conflicts by
 276                   editing the <SPAN
 277 CLASS="PRODUCTNAME"
 278 >eCos</SPAN
 279 > configuration save file
 280                   manually.</P
 281 ></DD
 282 ><DT
 283 ><TT
 284 CLASS="OPTION"
 285 >--ignore-errors</TT
 286 >, <TT
 287 CLASS="OPTION"
 288 >-i</TT
 289 ></DT
 290 ><DD
 291 ><P
 292 >By default, ecosconfig will exit with an error code if the current
 293 configuration contains any conflicts, and it is not possible to
 294 generate or update a build tree for such configurations. This
 295 qualifier causes ecosconfig to ignore such problems, and hence it is
 296 possible to generate a build tree even if there are still
 297 conflicts. Of course, there are no guarantees that the resulting
 298 system will actually do anything.</P
 299 ></DD
 300 ><DT
 301 ><TT
 302 CLASS="OPTION"
 303 >--verbose</TT
 304 >, <TT
 305 CLASS="OPTION"
 306 >-v</TT
 307 ></DT
 308 ><DD
 309 ><P
 310 >Display more information.</P
 311 ></DD
 312 ><DT
 313 ><TT
 314 CLASS="OPTION"
 315 >--quiet</TT
 316 >, <TT
 317 CLASS="OPTION"
 318 >-q</TT
 319 ></DT
 320 ><DD
 321 ><P
 322 >Display less information.</P
 323 ></DD
 324 ></DL
 325 ></DIV
 326 ><P
 327 >The <TT
 328 CLASS="OPTION"
 329 >--config</TT
 330 >, <TT
 331 CLASS="OPTION"
 332 >--prefix</TT
 333 > and
 334 <TT
 335 CLASS="OPTION"
 336 >--srcdir</TT
 337 > qualifiers can also be written with two arguments,
 338 for example:</P
 339 ><TABLE
 340 BORDER="5"
 341 BGCOLOR="#E0E0F0"
 342 WIDTH="70%"
 343 ><TR
 344 ><TD
 345 ><PRE
 346 CLASS="SCREEN"
 347 >ecosconfig --srcdir <TT
 348 CLASS="REPLACEABLE"
 349 ><I
 350 >&lt;dir&gt;</I
 351 ></TT
 352 > ...</PRE
 353 ></TD
 354 ></TR
 355 ></TABLE
 356 ><P
 357 >This simplifies filename completion with some shells.</P
 358 ></DIV
 359 ><DIV
 360 CLASS="SECT2"
 361 ><H2
 362 CLASS="SECT2"
 363 ><A
 364 NAME="AEN2480">ecosconfig commands</H2
 365 ><P
 366 >The available commands for
 367             <B
 368 CLASS="COMMAND"
 369 >ecosconfig</B
 370 > are as
 371             follows:</P
 372 ><P
 373 ></P
 374 ><DIV
 375 CLASS="VARIABLELIST"
 376 ><DL
 377 ><DT
 378 ><B
 379 CLASS="COMMAND"
 380 >list</B
 381 ></DT
 382 ><DD
 383 ><P
 384 >Lists the available packages, targets and
 385                   templates as installed in the <SPAN
 386 CLASS="PRODUCTNAME"
 387 >eCos</SPAN
 388 > repository.
 389                   Aliases and package versions are also
 390                   reported.</P
 391 ></DD
 392 ><DT
 393 ><B
 394 CLASS="COMMAND"
 395 >new &lt;target&gt; [&lt;template&gt; [&lt;version&gt;]]</B
 396 ></DT
 397 ><DD
 398 ><P
 399 >Creates a new <SPAN
 400 CLASS="PRODUCTNAME"
 401 >eCos</SPAN
 402 > configuration for
 403                   the specified target hardware and saves it. A
 404                   software template may also be specified. By default,
 405                   the template named &#8216;default&#8217; is used. If
 406                   the template version is not specified, the latest
 407                   version is used.</P
 408 ></DD
 409 ><DT
 410 ><B
 411 CLASS="COMMAND"
 412 >target &lt;target&gt;</B
 413 ></DT
 414 ><DD
 415 ><P
 416 >Changes the target hardware selection
 417                   for the <SPAN
 418 CLASS="PRODUCTNAME"
 419 >eCos</SPAN
 420 > configuration. This has the effect of
 421                   unloading packages supporting the target selected
 422                   previously and loading the packages which support
 423                   the new hardware. This command will be used
 424                   typically when switching between a simulator and
 425                   real hardware.</P
 426 ></DD
 427 ><DT
 428 ><B
 429 CLASS="COMMAND"
 430 >template &lt;template&gt; [&lt;version&gt;]</B
 431 ></DT
 432 ><DD
 433 ><P
 434 >Changes the template selection for the <SPAN
 435 CLASS="PRODUCTNAME"
 436 >eCos</SPAN
 437 >
 438                   configuration. This has the effect of unloading
 439                   packages specified by the template selected
 440                   previously and loading the packages specified by the
 441                   new template. By default, the latest version of the
 442                   specified template is used.</P
 443 ></DD
 444 ><DT
 445 ><B
 446 CLASS="COMMAND"
 447 >remove &lt;packages&gt;</B
 448 ></DT
 449 ><DD
 450 ><P
 451 >Removes the specified packages from the <SPAN
 452 CLASS="PRODUCTNAME"
 453 >eCos</SPAN
 454 >
 455                   configuration. This command will be used typically
 456                   when the template on which a configuration is based
 457                   contains packages which are not required.</P
 458 ></DD
 459 ><DT
 460 ><B
 461 CLASS="COMMAND"
 462 >add &lt;packages&gt;</B
 463 ></DT
 464 ><DD
 465 ><P
 466 >Adds the specified packages to the <SPAN
 467 CLASS="PRODUCTNAME"
 468 >eCos</SPAN
 469 > configuration. This
 470 command will be used typically when the template on which a
 471 configuration is based does not contain all the packages which are
 472 required.For example, add-on packages provided by third parties will
 473 not be known to the standard templates, so they will have to be added
 474 explicitly. </P
 475 ></DD
 476 ><DT
 477 ><B
 478 CLASS="COMMAND"
 479 >version &lt;version&gt; &lt;packages&gt;</B
 480 ></DT
 481 ><DD
 482 ><P
 483 >Selects the specified version of a
 484                   number of packages in the <SPAN
 485 CLASS="PRODUCTNAME"
 486 >eCos</SPAN
 487 > configuration. By
 488                   default, the most recent version of each package is
 489                   used. This command will be used typically when an
 490                   older version of a package is required.</P
 491 ></DD
 492 ><DT
 493 ><B
 494 CLASS="COMMAND"
 495 >check</B
 496 ></DT
 497 ><DD
 498 ><P
 499 >Presents the following information
 500                   concerning the current configuration:</P
 501 ><P
 502 ></P
 503 ><OL
 504 TYPE="1"
 505 ><LI
 506 ><P
 507 >the selected target hardware</P
 508 ></LI
 509 ><LI
 510 ><P
 511 >the selected template</P
 512 ></LI
 513 ><LI
 514 ><P
 515 >additional packages</P
 516 ></LI
 517 ><LI
 518 ><P
 519 >removed packages</P
 520 ></LI
 521 ><LI
 522 ><P
 523 >the selected version of packages
 524                       where this is not the most recent
 525                       version</P
 526 ></LI
 527 ><LI
 528 ><P
 529 >conflicts in the current configuration</P
 530 ></LI
 531 ></OL
 532 ></DD
 533 ><DT
 534 ><B
 535 CLASS="COMMAND"
 536 >resolve</B
 537 ></DT
 538 ><DD
 539 ><P
 540 >Resolves conflicts identified in the
 541                   current <SPAN
 542 CLASS="PRODUCTNAME"
 543 >eCos</SPAN
 544 > configuration by invoking an inference
 545                   capability. Resolved conflicts are reported, but not
 546                   all conflicts may be resolvable. This command will
 547                   be used typically following manual editing of the
 548                   configuration.</P
 549 ></DD
 550 ><DT
 551 ><B
 552 CLASS="COMMAND"
 553 >export &lt;file&gt;</B
 554 ></DT
 555 ><DD
 556 ><P
 557 >Exports a minimal <SPAN
 558 CLASS="PRODUCTNAME"
 559 >eCos</SPAN
 560 > configuration
 561                   save file with the specified name. This file
 562                   contains only those options which do not have their
 563                   default value. Such files are used typically to
 564                   transfer option values from one configuration to
 565                   another.</P
 566 ></DD
 567 ><DT
 568 ><B
 569 CLASS="COMMAND"
 570 >import &lt;file&gt;</B
 571 ></DT
 572 ><DD
 573 ><P
 574 >Imports a minimal <SPAN
 575 CLASS="PRODUCTNAME"
 576 >eCos</SPAN
 577 > configuration
 578                   save file with the specified name. The values of
 579                   those options specified in the file are applied to
 580                   the current configuration.</P
 581 ></DD
 582 ><DT
 583 ><B
 584 CLASS="COMMAND"
 585 >tree</B
 586 ></DT
 587 ><DD
 588 ><P
 589 >Generates a build tree based on the current <SPAN
 590 CLASS="PRODUCTNAME"
 591 >eCos</SPAN
 592 >
 593                   configuration. This command will be used typically
 594                   just before building <SPAN
 595 CLASS="PRODUCTNAME"
 596 >eCos</SPAN
 597 >.Normally a build tree can
 598 only be generated if if the configuration has no unresolved
 599 conflicts, but <TT
 600 CLASS="OPTION"
 601 >--ignore-errors</TT
 602 > can be used to override
 603 this.</P
 604 ></DD
 605 ></DL
 606 ></DIV
 607 ></DIV
 608 ></DIV
 609 ><DIV
 610 CLASS="NAVFOOTER"
 611 ><HR
 612 ALIGN="LEFT"
 613 WIDTH="100%"><TABLE
 614 SUMMARY="Footer navigation table"
 615 WIDTH="100%"
 616 BORDER="0"
 617 CELLPADDING="0"
 618 CELLSPACING="0"
 619 ><TR
 620 ><TD
 621 WIDTH="33%"
 622 ALIGN="left"
 623 VALIGN="top"
 624 ><A
 625 HREF="manual-configuration.html"
 626 ACCESSKEY="P"
 627 >Prev</A
 628 ></TD
 629 ><TD
 630 WIDTH="34%"
 631 ALIGN="center"
 632 VALIGN="top"
 633 ><A
 634 HREF="ecos-user-guide.html"
 635 ACCESSKEY="H"
 636 >Home</A
 637 ></TD
 638 ><TD
 639 WIDTH="33%"
 640 ALIGN="right"
 641 VALIGN="top"
 642 ><A
 643 HREF="conflicts-and-constraints.html"
 644 ACCESSKEY="N"
 645 >Next</A
 646 ></TD
 647 ></TR
 648 ><TR
 649 ><TD
 650 WIDTH="33%"
 651 ALIGN="left"
 652 VALIGN="top"
 653 >Manual Configuration</TD
 654 ><TD
 655 WIDTH="34%"
 656 ALIGN="center"
 657 VALIGN="top"
 658 ><A
 659 HREF="manual-configuration.html"
 660 ACCESSKEY="U"
 661 >Up</A
 662 ></TD
 663 ><TD
 664 WIDTH="33%"
 665 ALIGN="right"
 666 VALIGN="top"
 667 >Conflicts and constraints</TD
 668 ></TR
 669 ></TABLE
 670 ></DIV
 671 ></BODY
 672 ></HTML
 673 >