rtems/rtems-source-builder
1
0
Fork 0
mirror of https://git.rtems.org/rtems-source-builder synced 2024-10-09 07:15:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document fixes reported by users.

Browse Source
This commit is contained in:
Chris Johns 2013-04-14 17:37:39 +10:00
parent 4351cf4d7f
commit 69f9806cc1
1 changed files with 50 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
doc/source-builder.txt
View File

@ -124,7 +124,7 @@ RTEMS Source Builder environment is ok <3>
The checking tool will output a list of executable files not found if problems
are detected. Locate those executable files and install them. You may also be
given a list of warnings about executable files not in the expected location
how-ever the executable was located somewhere in your environment's path. You
however the executable was located somewhere in your environment's path. You
will need to check each tool to determine if this is an issue. An executable
not in the standard location may indicate it is not the host operating system's
standard tool. It maybe ok or it could be buggy, only you can determine this.
@ -228,9 +228,9 @@ Examining: ../source-builder/config <2>
set files.
<6> Unstable tool sets are used by RTEMS developers to test new tool sets. You
are welcome to try them but you must remember they are unstable, can change
at point in time and your application may not work. If you have an issue
with a production tool it may pay to try the unstable tool to see if it has
been resolved.
at any point in time and your application may not work. If you have an
issue with a production tool it may pay to try the unstable tool to see if
it has been resolved.
Building
~~~~~~~~
@ -347,6 +347,12 @@ gcc version 4.7.2 20120920 <4>
recorded in the version string. The hash allows you to track from a GCC
executable back to the original source used to build it.
NOTE: The RTEMS thread model enables specific hooks in GCC so applications
built with RTEMS tools need the RTEMS runtime to operate correctly. You can use
RTEMS tools to build bare metal component but it is more difficult than with a
bare metal tool chain and you need to know what you are doing at a low
level. The RTEMS Source Builder can build bare metal tool chains.
Installing and Tar Files
~~~~~~~~~~~~~~~~~~~~~~~~
@ -355,14 +361,24 @@ it can create a build set tar file or a tar file per package built. The normal
and default behaviour is to let the RTEMS Source Builder install the tools. The
source will be downloaded, built, installed and cleaned up.
The tar files are created with the full build prefix present. This can cause
The tar files are created with the full build prefix present and if you follow
the examples given in this documentation the path is absolute. This can cause
problems if you are installing on a host you do not have super user or
administrator rights on if the prefix path references part you do not have
write access t0o. You can use the +--strip-components+ option in tar if your
tar file supports it to remove the parts you do not have write access too or
you may need to unpack the tar file somewhere and copy the file tree from the
level you have write access from. Embedding the full prefix path in the tar
files lets you know what the prefix is.
administrator rights on because the prefix path may references part you do not
have write access too and tar will not extract the files. You can use the
+--strip-components+ option in tar if your host tar application supports it to
remove the parts you do not have write access too or you may need to unpack the
tar file somewhere and copy the file tree from the level you have write access
from. Embedding the full prefix path in the tar files lets you know what the
prefix is and is recommended. For example if
`/home/chris/development/rtems/4.11` is the prefix used you cannot
change directory to the root (`/`) and install because the `/home` is root
access only. To install you would:
-------------------------------------------------------------
$ cd
$ tar --strip-components=3 -xjf rtems-4.11-sparc-rtems4.11-1.tar.bz2
-------------------------------------------------------------
A build set tar file is created by adding `--bset-tar-file` option to the
`sb-set-builder` command.
@ -494,7 +510,7 @@ changing world of the host development machines. If your tool set is binary and
you have lost the ability to build it you have lost a degree of control and
flexibility open source gives you. Fast moving host environments are
fantastic. We have powerful multi-core computers with huge amounts of memory
and state of the art operating systems to run on them how-ever the product or
and state of the art operating systems to run on them however the product or
project you are part of may need to be maintained well past the life time of
these host. Being able to build from source an important and critical part of
this process because you can move to a newer host and create an equivalent tool
@ -508,7 +524,7 @@ GNU C compiler (gcc) currently uses a number of 3rd party libraries internally
processor is dynamically linked against the host's version of these libraries
any change in the host's configuration may effect you. The changes the host's
package management system makes may be perfectly reasonable in relation to the
distribution being managed how-ever this may not extend to you and your
distribution being managed however this may not extend to you and your
tools. Building your tools from source and controlling the specific version of
these dependent parts means you are not exposing yourself to unexpected and
often difficult to resolve problems. On the other side you need to make sure
@ -532,7 +548,7 @@ Bugs, Crashes, and Build Failures
---------------------------------
The RTEMS Source Builder is a Python program and every care is taken to test
the code how-ever bugs, crashes, and build failure can and do happen. If you
the code however bugs, crashes, and build failure can and do happen. If you
find a bug please report it via the RTEMS Bug tracker tool Bugzilla:
https://www.rtems.org/bugzilla/
@ -831,7 +847,7 @@ Scripting
Configuration files specify how to build a package. Configuration files are
scripts and have a +.cfg+ file extension. The script format is based loosely on
the RPM spec file format how-ever the use and purpose in this tool does not
the RPM spec file format however the use and purpose in this tool does not
compare with the functionality and therefore the important features of the spec
format RPM needs and uses.
@ -1163,9 +1179,9 @@ configuration building the package changes.
The +%version% macro sets the version the package. If the package is a single
component it tracks that component's version number. For example in the
_libusb_ configuration the +%version+ is the same as +%libusb_version+,
how-ever in a GCC with Newlib configuration there is no single version
number. In this case the GCC version is used.
_libusb_ configuration the +%version+ is the same as +%libusb_version+, however
in a GCC with Newlib configuration there is no single version number. In this
case the GCC version is used.
-------------------------------------------------------------
Version: %{gcc_version}
@ -1481,10 +1497,10 @@ between them and this makes existing tool incompatible with RTEMS.
RTEMS allows architectures to have different tool versions and patches. The
large number of architectures RTEMS supports can make it difficult to get a
common stable version of all the packages. An architecture may require a recent
GCC because an existing bug has been fixed, how-ever the more recent version
may have a bug in other architecture. Architecture specific patches should be
GCC because an existing bug has been fixed, however the more recent version may
have a bug in other architecture. Architecture specific patches should be
limited to the architecture it relates to. The patch may fix a problem on the
effect architecture how-ever it could introduce a problem in another
effect architecture however it could introduce a problem in another
architecture. Limit exposure limits any possible crosstalk between
architectures.
@ -1643,17 +1659,17 @@ Clean away the results of a build even if the build fails. This is normally
used with `--keep-going` when regression testing to see which build sets
fail to build. It keeps the disk usage down.
+--jobs+;;
Control the number of jobs make is given. The jobs can 'none' for only 1 job,
'half' so the number of jobs is half the number of detected cores, a fraction
such as '0.25' so the number of jobs is a quarter of the number of detected
cores and a number such as '25' which forces the number of jobs to that
number.
Control the number of jobs make is given. The jobs can be 'none' for only 1
job, 'half' so the number of jobs is half the number of detected cores, a
fraction such as '0.25' so the number of jobs is a quarter of the number of
detected cores and a number such as '25' which forces the number of jobs to
that number.
+--host+;;
Set the host triplet value. Becareful with this option.
Set the host triplet value. Be careful with this option.
+--build+;;
Set the build triplet. Becareful with this option.
Set the build triplet. Be careful with this option.
+--target+;;
Set the target triplet. Becareful with this option. This is useful if you have
Set the target triplet. Be careful with this option. This is useful if you have
a generic configuration script that can work for a range of architectures.
+--prefix path+;;
Tools build prefix, ie where they are installed.
@ -1844,7 +1860,7 @@ Windows tool sets are supported creating native Windows executable. Native
Windows tools are built using a MinGW compiler and do not need any extra
libraries or emulation layer to run once built. The tools understand and use
standard Windows paths and integrate easly into Windows IDE environments. A
shell maybe needed to build other parts of your system how-ever if your
shell maybe needed to build other parts of your system however if your
development tools are all native Windows tool you can easly integrate these
tool sets.
@ -1992,12 +2008,12 @@ way to build tools on hosts that did not support RPMs. At the time the RTEMS
tools maintainer only used spec files to create various packages. This meant I
had either spec files, RPM files or SRPM files. The RPM and SPRM files where
useless because you needed an 'rpm' type tool to extract and manage them. There
are versions of 'rpm' for a number of non-RPM hosts how-ever these proved to be
in various broken states and random-ally maintained. The solution I settled on
was to use spec files so I wrote a Python based tool that parsed the spec file
are versions of 'rpm' for a number of non-RPM hosts however these proved to be
in various broken states and randomly maintained. The solution I settled on was
to use spec files so I wrote a Python based tool that parsed the spec file
format and allowed me to create a shell script I could run to build the
package. This approach proved successful and I was able to track the RPM
version of the RTEMS tools on a non-RPM host over a number of years. How-ever
version of the RTEMS tools on a non-RPM host over a number of years. however
the SpecBuilder tool did not help me build tools or other packages not related
to the RTEMS project where there was no spec file I could use so I needed
another tool. Rather than start again I decided to take the parsing code for