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 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 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 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 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 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. 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. set files.
<6> Unstable tool sets are used by RTEMS developers to test new tool sets. You <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 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 at any point in time and your application may not work. If you have an
with a production tool it may pay to try the unstable tool to see if it has issue with a production tool it may pay to try the unstable tool to see if
been resolved. it has been resolved.
Building 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 recorded in the version string. The hash allows you to track from a GCC
executable back to the original source used to build it. 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 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 and default behaviour is to let the RTEMS Source Builder install the tools. The
source will be downloaded, built, installed and cleaned up. 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 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 administrator rights on because the prefix path may references part you do not
write access t0o. You can use the +--strip-components+ option in tar if your have write access too and tar will not extract the files. You can use the
tar file supports it to remove the parts you do not have write access too or +--strip-components+ option in tar if your host tar application supports it to
you may need to unpack the tar file somewhere and copy the file tree from the remove the parts you do not have write access too or you may need to unpack the
level you have write access from. Embedding the full prefix path in the tar tar file somewhere and copy the file tree from the level you have write access
files lets you know what the prefix is. 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 A build set tar file is created by adding `--bset-tar-file` option to the
`sb-set-builder` command. `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 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 flexibility open source gives you. Fast moving host environments are
fantastic. We have powerful multi-core computers with huge amounts of memory 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 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 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 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 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 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 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 tools. Building your tools from source and controlling the specific version of
these dependent parts means you are not exposing yourself to unexpected and 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 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 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: find a bug please report it via the RTEMS Bug tracker tool Bugzilla:
https://www.rtems.org/bugzilla/ https://www.rtems.org/bugzilla/
@ -831,7 +847,7 @@ Scripting
Configuration files specify how to build a package. Configuration files are 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 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 compare with the functionality and therefore the important features of the spec
format RPM needs and uses. 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 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 component it tracks that component's version number. For example in the
_libusb_ configuration the +%version+ is the same as +%libusb_version+, _libusb_ configuration the +%version+ is the same as +%libusb_version+, however
how-ever in a GCC with Newlib configuration there is no single version in a GCC with Newlib configuration there is no single version number. In this
number. In this case the GCC version is used. case the GCC version is used.
------------------------------------------------------------- -------------------------------------------------------------
Version: %{gcc_version} 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 RTEMS allows architectures to have different tool versions and patches. The
large number of architectures RTEMS supports can make it difficult to get a 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 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 GCC because an existing bug has been fixed, however the more recent version may
may have a bug in other architecture. Architecture specific patches should be 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 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 architecture. Limit exposure limits any possible crosstalk between
architectures. 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 used with `--keep-going` when regression testing to see which build sets
fail to build. It keeps the disk usage down. fail to build. It keeps the disk usage down.
+--jobs+;; +--jobs+;;
Control the number of jobs make is given. The jobs can 'none' for only 1 job, Control the number of jobs make is given. The jobs can be 'none' for only 1
'half' so the number of jobs is half the number of detected cores, a fraction job, 'half' so the number of jobs is half the number of detected cores, a
such as '0.25' so the number of jobs is a quarter of the number of detected fraction such as '0.25' so the number of jobs is a quarter of the number of
cores and a number such as '25' which forces the number of jobs to that detected cores and a number such as '25' which forces the number of jobs to
number. that number.
+--host+;; +--host+;;
Set the host triplet value. Becareful with this option. Set the host triplet value. Be careful with this option.
+--build+;; +--build+;;
Set the build triplet. Becareful with this option. Set the build triplet. Be careful with this option.
+--target+;; +--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. a generic configuration script that can work for a range of architectures.
+--prefix path+;; +--prefix path+;;
Tools build prefix, ie where they are installed. 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 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 libraries or emulation layer to run once built. The tools understand and use
standard Windows paths and integrate easly into Windows IDE environments. A 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 development tools are all native Windows tool you can easly integrate these
tool sets. 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 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 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 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 are versions of 'rpm' for a number of non-RPM hosts however these proved to be
in various broken states and random-ally maintained. The solution I settled on in various broken states and randomly maintained. The solution I settled on was
was to use spec files so I wrote a Python based tool that parsed the spec file 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 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 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 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 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 another tool. Rather than start again I decided to take the parsing code for