diff options
author | Chris Johns <chrisj@rtems.org> | 2012-11-05 18:04:16 +1100 |
---|---|---|
committer | Chris Johns <chrisj@rtems.org> | 2012-11-05 18:04:16 +1100 |
commit | d7a023a4c1efeca119716e0672d072bc5c3a892d (patch) | |
tree | 7bb5637d41a32c35734ea103c00b215c02f10ba9 | |
parent | Remove the autotools. You need them to pass check. (diff) | |
download | rtems-source-builder-d7a023a4c1efeca119716e0672d072bc5c3a892d.tar.bz2 |
Add documentation.
30 files changed, 172 insertions, 0 deletions
diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..3af9e6f --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +.lock-* +build diff --git a/doc/images/icons/README b/doc/images/icons/README new file mode 100644 index 0000000..f12b2a7 --- /dev/null +++ b/doc/images/icons/README @@ -0,0 +1,5 @@ +Replaced the plain DocBook XSL admonition icons with Jimmac's DocBook +icons (http://jimmac.musichall.cz/ikony.php3). I dropped transparency +from the Jimmac icons to get round MS IE and FOP PNG incompatibilies. + +Stuart Rackham diff --git a/doc/images/icons/callouts/1.png b/doc/images/icons/callouts/1.png Binary files differnew file mode 100644 index 0000000..7d47343 --- /dev/null +++ b/doc/images/icons/callouts/1.png diff --git a/doc/images/icons/callouts/10.png b/doc/images/icons/callouts/10.png Binary files differnew file mode 100644 index 0000000..997bbc8 --- /dev/null +++ b/doc/images/icons/callouts/10.png diff --git a/doc/images/icons/callouts/11.png b/doc/images/icons/callouts/11.png Binary files differnew file mode 100644 index 0000000..ce47dac --- /dev/null +++ b/doc/images/icons/callouts/11.png diff --git a/doc/images/icons/callouts/12.png b/doc/images/icons/callouts/12.png Binary files differnew file mode 100644 index 0000000..31daf4e --- /dev/null +++ b/doc/images/icons/callouts/12.png diff --git a/doc/images/icons/callouts/13.png b/doc/images/icons/callouts/13.png Binary files differnew file mode 100644 index 0000000..14021a8 --- /dev/null +++ b/doc/images/icons/callouts/13.png diff --git a/doc/images/icons/callouts/14.png b/doc/images/icons/callouts/14.png Binary files differnew file mode 100644 index 0000000..64014b7 --- /dev/null +++ b/doc/images/icons/callouts/14.png diff --git a/doc/images/icons/callouts/15.png b/doc/images/icons/callouts/15.png Binary files differnew file mode 100644 index 0000000..0d65765 --- /dev/null +++ b/doc/images/icons/callouts/15.png diff --git a/doc/images/icons/callouts/2.png b/doc/images/icons/callouts/2.png Binary files differnew file mode 100644 index 0000000..5d09341 --- /dev/null +++ b/doc/images/icons/callouts/2.png diff --git a/doc/images/icons/callouts/3.png b/doc/images/icons/callouts/3.png Binary files differnew file mode 100644 index 0000000..ef7b700 --- /dev/null +++ b/doc/images/icons/callouts/3.png diff --git a/doc/images/icons/callouts/4.png b/doc/images/icons/callouts/4.png Binary files differnew file mode 100644 index 0000000..adb8364 --- /dev/null +++ b/doc/images/icons/callouts/4.png diff --git a/doc/images/icons/callouts/5.png b/doc/images/icons/callouts/5.png Binary files differnew file mode 100644 index 0000000..4d7eb46 --- /dev/null +++ b/doc/images/icons/callouts/5.png diff --git a/doc/images/icons/callouts/6.png b/doc/images/icons/callouts/6.png Binary files differnew file mode 100644 index 0000000..0ba694a --- /dev/null +++ b/doc/images/icons/callouts/6.png diff --git a/doc/images/icons/callouts/7.png b/doc/images/icons/callouts/7.png Binary files differnew file mode 100644 index 0000000..472e96f --- /dev/null +++ b/doc/images/icons/callouts/7.png diff --git a/doc/images/icons/callouts/8.png b/doc/images/icons/callouts/8.png Binary files differnew file mode 100644 index 0000000..5e60973 --- /dev/null +++ b/doc/images/icons/callouts/8.png diff --git a/doc/images/icons/callouts/9.png b/doc/images/icons/callouts/9.png Binary files differnew file mode 100644 index 0000000..a0676d2 --- /dev/null +++ b/doc/images/icons/callouts/9.png diff --git a/doc/images/icons/caution.png b/doc/images/icons/caution.png Binary files differnew file mode 100644 index 0000000..9a8c515 --- /dev/null +++ b/doc/images/icons/caution.png diff --git a/doc/images/icons/example.png b/doc/images/icons/example.png Binary files differnew file mode 100644 index 0000000..1199e86 --- /dev/null +++ b/doc/images/icons/example.png diff --git a/doc/images/icons/home.png b/doc/images/icons/home.png Binary files differnew file mode 100644 index 0000000..37a5231 --- /dev/null +++ b/doc/images/icons/home.png diff --git a/doc/images/icons/important.png b/doc/images/icons/important.png Binary files differnew file mode 100644 index 0000000..be685cc --- /dev/null +++ b/doc/images/icons/important.png diff --git a/doc/images/icons/next.png b/doc/images/icons/next.png Binary files differnew file mode 100644 index 0000000..64e126b --- /dev/null +++ b/doc/images/icons/next.png diff --git a/doc/images/icons/note.png b/doc/images/icons/note.png Binary files differnew file mode 100644 index 0000000..7c1f3e2 --- /dev/null +++ b/doc/images/icons/note.png diff --git a/doc/images/icons/prev.png b/doc/images/icons/prev.png Binary files differnew file mode 100644 index 0000000..3e8f12f --- /dev/null +++ b/doc/images/icons/prev.png diff --git a/doc/images/icons/tip.png b/doc/images/icons/tip.png Binary files differnew file mode 100644 index 0000000..f087c73 --- /dev/null +++ b/doc/images/icons/tip.png diff --git a/doc/images/icons/up.png b/doc/images/icons/up.png Binary files differnew file mode 100644 index 0000000..2db1ce6 --- /dev/null +++ b/doc/images/icons/up.png diff --git a/doc/images/icons/warning.png b/doc/images/icons/warning.png Binary files differnew file mode 100644 index 0000000..d41edb9 --- /dev/null +++ b/doc/images/icons/warning.png diff --git a/doc/images/rtemswhitebg.jpg b/doc/images/rtemswhitebg.jpg Binary files differnew file mode 100644 index 0000000..f883f2c --- /dev/null +++ b/doc/images/rtemswhitebg.jpg diff --git a/doc/source-builder.txt b/doc/source-builder.txt new file mode 100644 index 0000000..887215c --- /dev/null +++ b/doc/source-builder.txt @@ -0,0 +1,145 @@ +Source Builder +============== +Chris Johns <chrisj@rtems.org> +1.0, November 2012 +:doctype: book +:toc: +:icons: +:numbered: + +image:images/rtemswhitebg.jpg["RTEMS",width="20%"] + +Introduction +------------ + +The Source Builder is a tool to aid building packages from source. It is not a +package manager. It is just helps consolidate the details that you need to know +to build a package from source. The tool is mainly aimed at those users who +need to maintain tool sets for embedded type development, that is +cross-compiled compiled tool chains, debuggers, and debugging aids. It is not +limited to this role but designed to fit with-in that specific niche. + +The Source Builder attempts to support any host environment that runs Python +and you can build the package on. It is not some sort of magic that can take +any piece of source code and make it build. Someone at some point in time has +figured out how to build that package from source and taught this tool. + +The Source Builder has two types configuration data. The first is configuration +files and these are scripts based on the RPM spec file format that detail the +steps needed to build a package. The steps are 'preparation', 'building', and +'installing'. The second set of configuration files are 'build sets'. A build +set describes a collection of packages you want built together. For example the +GNU tool set is autoconf, automake, binutils, gcc, and gdb. This is the typical +suite of tools you need for an embedded cross-development type project. + +The Source Builder does not interact with any host package management +system. There is no automatic dependence checking between various packages you +build or your host system may have installed. We assume you know what are doing +or the build sets and configuration files you are using have been created by +developers who do. A buld set should provide a known working configuration. + +Why build from source ? +~~~~~~~~~~~~~~~~~~~~~~~ + +If you are developing a system or product that has a long shelf life or is used +in a critical piece of infastructure that has a long life cycle being able to +build from source is important. It insulates the project from the fast ever +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 running on them. 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 +set. + +Building from source provides you with control over the configuration of the +package you are building. If all or the most important dependent parts are +built from source you limit the exposure to host variations. For example the +GNU C compiler (gcc) currently uses a number of 3rd party libraries internally +(gmp, mpfr, etc). If your validated compiler generating code for your target +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 reasonible in relation to the +distribution being managed how-ever 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 +your tools build and work with newer versions of the host operating +sytem. Given the stability of standards based libraries like 'libc' and ever +improving support for standard header file locations this task is becoming +easier. + +History +~~~~~~~ + +The Source Builder is a stand alone tool based on another tool called the +'SpecBuilder'. The SpecBuilder was written for the RTEMS project too give me a +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 randomally 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 +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 +the spec file format and build a new tool called the Source Builder. + +Quick Start +----------- + +Check out the Source Builder tool from git: + +------------------------------------------------------------- +$ git clone git://git.rtems.org/source-builder.git +------------------------------------------------------------- + +The first step is to check if your host is set up correctly: + +------------------------------------------------------------- +$ source-builder/sb-check +warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1> +warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump +error: exe: not found: (_xz) /usr/local/bin/xz <2> +Source Builder environent is not correctly set up +$ source-builder/sb-check +Source Builder environent is ok <3> +------------------------------------------------------------- + +<1> A tool is in the environment path but does not match the shown path. +<2> The executable 'xz' is not found. +<3> The host's environment is set up correct. + +If there are problems you are given a list of executables that cannot be +found. You may also be given a list of warnings about executables not in the +expected location how-ever the executable was located somewhere in your +environment's path. You will need to check the specific host section to resolve +these issues. + +Create a suitable build directory away from the Source Builder source change +into that directory and build a GNU tool set: + +------------------------------------------------------------- +$ mkdir gnu-tools <1> +$ cd gnu-tools +$ ../source-builder/sb-set-builder <2> --log=l.txt <3> --force <4> \ + --prefix=$HOME/gnu-tools-1 <5> --target=arm-eabi <6> gnu-toolset-4.6 <7> +------------------------------------------------------------- + +<1> Make a build directory you can delete when finished. +<2> The Source Builder command to build a set of tools. +<3> Capture the output to a log file. +<4> The force option will create any needed directories and allow the build to +proceed if your host is not set up. +<5> Give the tools a suitable prefix. This is the location you install the +tools into once they have built. +<6> The gnu-toolset requires you set a target. In this case the tool set will +be a generic unpatched version of GCC 4.6 for a bare metel the ARM processor. +<7> The build set. + diff --git a/doc/wscript b/doc/wscript new file mode 100644 index 0000000..9685ebf --- /dev/null +++ b/doc/wscript @@ -0,0 +1,20 @@ +# +# Waf build script to build the Source Builder Documentation. +# + +version = "1.0.0" + +def configure(ctx): + ctx.env.ASCIIDOC = ctx.find_program(['asciidoc.py'], mandatory = True) + ctx.env.ASCIIDOC_FLAGS = ['-b', 'html', '-a', 'data-uri', '-a', 'icons', '-a', 'max-width=55em-a'] + +def build(ctx): + ctx(target = 'source-builder.html', source = 'source-builder.txt') + +import waflib.TaskGen +waflib.TaskGen.declare_chain(name = 'html', + rule = '${ASCIIDOC} ${ASCIIDOC_FLAGS} -o ${TGT} ${SRC}', + shell = False, + ext_in = '.txt', + ext_out = '.html', + reentrant = False) |