From e31ae4dfeddefe8bf09a2c14d2c3f80bd13a030b Mon Sep 17 00:00:00 2001 From: Robert Schwebel Date: Sun, 22 Feb 2004 21:22:23 +0000 Subject: Initial manual submission git-svn-id: https://svn.pengutronix.de/svn/ptxdist/trunk@1077 33e552b5-05e3-0310-8538-816dae2090ed --- Documentation/manual/Makefile | 19 ++ Documentation/manual/PTXdist-Manual.tex | 238 ++++++++++++++ Documentation/manual/appendix/licenses.tex | 345 +++++++++++++++++++++ Documentation/manual/appendix/releases.tex | 6 + Documentation/manual/devel/kconfig.tex | 4 + Documentation/manual/devel/macros.tex | 4 + Documentation/manual/devel/makefile-targets.tex | 4 + Documentation/manual/devel/new-packages.tex | 4 + Documentation/manual/figures/menuconfig.png | Bin 0 -> 23923 bytes Documentation/manual/intro/embedded-linux.tex | 103 ++++++ .../manual/intro/maintaining-userlands.tex | 108 +++++++ Documentation/manual/user/building-blocks.tex | 138 +++++++++ Documentation/manual/user/config-system.tex | 4 + Documentation/manual/user/i386-generic.tex | 115 +++++++ Documentation/manual/user/running-make.tex | 121 ++++++++ Documentation/manual/user/subtargets.tex | 81 +++++ Documentation/manual/user/toolchain-targets.tex | 4 + 17 files changed, 1298 insertions(+) create mode 100644 Documentation/manual/Makefile create mode 100644 Documentation/manual/PTXdist-Manual.tex create mode 100644 Documentation/manual/appendix/licenses.tex create mode 100644 Documentation/manual/appendix/releases.tex create mode 100644 Documentation/manual/devel/kconfig.tex create mode 100644 Documentation/manual/devel/macros.tex create mode 100644 Documentation/manual/devel/makefile-targets.tex create mode 100644 Documentation/manual/devel/new-packages.tex create mode 100644 Documentation/manual/figures/menuconfig.png create mode 100644 Documentation/manual/intro/embedded-linux.tex create mode 100644 Documentation/manual/intro/maintaining-userlands.tex create mode 100644 Documentation/manual/user/building-blocks.tex create mode 100644 Documentation/manual/user/config-system.tex create mode 100644 Documentation/manual/user/i386-generic.tex create mode 100644 Documentation/manual/user/running-make.tex create mode 100644 Documentation/manual/user/subtargets.tex create mode 100644 Documentation/manual/user/toolchain-targets.tex (limited to 'Documentation') diff --git a/Documentation/manual/Makefile b/Documentation/manual/Makefile new file mode 100644 index 000000000..6ed2415d5 --- /dev/null +++ b/Documentation/manual/Makefile @@ -0,0 +1,19 @@ +pdf: PTXdist-Manual.pdf +dvi: PTXdist-Manual.dvi + +final: + pdflatex PTXdist-Manual + pdflatex PTXdist-Manual + +.PHONY: PTXdist-Manual.pdf +PTXdist-Manual.pdf: PTXdist-Manual.tex + pdflatex PTXdist-Manual + +.PHONY: PTXdist-Manual.dvi +PTXdist-Manual.dvi: PTXdist-Manual.tex + latex PTXdist-Manual + +.PHONY: clean +clean: + rm -f *.aux *.log *.dvi *.out *.toc *.idx + rm -f PTXdist-Manual.pdf PTXdist-Manual.ps diff --git a/Documentation/manual/PTXdist-Manual.tex b/Documentation/manual/PTXdist-Manual.tex new file mode 100644 index 000000000..b9e845d6a --- /dev/null +++ b/Documentation/manual/PTXdist-Manual.tex @@ -0,0 +1,238 @@ +\documentclass[10pt,a4paper,pointlessnumbers,bibtotocnumbered,headsepline]{scrbook} +\usepackage{longtable,tabularx} +%\usepackage{supertabular} +\usepackage{afterpage} +\usepackage{verbatim} +\usepackage{fancybox} +\usepackage{makeidx} +\usepackage{afterpage} +%\usepackage[draft]{graphicx} +\usepackage{graphicx} +\usepackage{bigstrut} +\usepackage[small]{caption2} +\abovecaptionskip1.5mm +\belowcaptionskip5mm +\renewcommand{\captionfont}{\small\itshape} +\renewcommand{\captionlabelfont}{\bfseries} +\LTpost=\belowcaptionskip +\usepackage[colorlinks]{hyperref} + +% palatino fonts are standard +% --------------------------- +\usepackage{palatino} + +% listings +% -------- +\usepackage{listings} +\lstloadlanguages{C} +\lstset{ + basicstyle=\scriptsize, + keywordstyle=\bfseries, + commentstyle=\slshape, + stringstyle=\ttfamily, +% RS: seems to have changed in newer LaTeX packets... +% labelstep=5, +% labelstyle=\tiny, +% indent=20pt +} + +% paper format +% ------------ +\usepackage{geometry} +\geometry{dvips, pdftex} +%\geometry{paperwidth=210mm} +%\geometry{paperheight=297mm} +%\geometry{top=12mm} +%\geometry{bottom=20mm} +%\geometry{textwidth=170mm} +%\geometry{left=20mm} +%\geometry{twosideshift=10mm} +%\geometry{headsep=0mm} +%\geometry{head=40mm} +%\geometry{footskip=12mm} + +\evensidemargin0mm +\oddsidemargin0mm + +% head- and footlines +% ------------------- + +%\usepackage{fancyhdr} +%\usepackage{psboxit} +%%\renewcommand{\headrule}{\includegraphics{longline}} +%\renewcommand{\sectionmark}[1]{\markboth{\thesection #1 Bla}} +%\lhead[\sf Kapitel \thechapter]{\fancyplain{}} +%\rhead[\fancyplain{}]{\sf \rightmark} +%%\lfoot[\includegraphics{shortline}\\\sf\thepage]{\fancyplain{}} +%\lfoot[\rule{12mm}{0.5pt}\\\sf\thepage]{\fancyplain{}} +%%\rfoot[\fancyplain{}]{\includegraphics{shortline}\\\sf\thepage} +%\rfoot[\fancyplain{}]{\rule{12mm}{0.5pt}\\\sf\thepage} +%\cfoot{\fancyplain{}} + + +\raggedbottom + +% PDF parameters +% \pdfcompresslevel=9 + + +% please make me an index +\makeindex + +% some spacings +\setlength{\parindent}{0 pt} +\setlength{\parskip}{0.5\baselineskip plus 2 pt minus 2 pt} +%\setlength{\parskip}{1.5ex plus 0.5ex minus 0.3ex} +\setlength{\baselineskip}{1\baselineskip plus 0pt minus 0pt} + +% space on top and bottom of the page which can be used by floatingfigures +\renewcommand{\topfraction}{0.7} +\renewcommand{\bottomfraction}{0.7} +\renewcommand{\floatpagefraction}{0.7} + +% tolerance of the characters +\tolerance=2000 +\emergencystretch=20pt + +% avoid Hurenkinder and Schusterjungen +\clubpenalty=9999\relax +\widowpenalty=9999\relax + +% don't allow page breaks in footnotes +\interfootnotelinepenalty=10000 + + +% headline +%\pagestyle{fancyplain} + + +% environment for code samples +% ---------------------------- +\newenvironment{code}{\begingroup\verbatim}{\endverbatim\endgroup} +\newenvironment{smallcode}{\begingroup\footnotesize\verbatim}{\endverbatim\endgroup} + + +% for test purposes: make line on the baseline +\newcommand{\HR}{\rule{1em}{.4pt}} + +% itemize environment with less space +\newenvironment{myitemize}{ + \begin{itemize} + \setlength{\itemsep}{-3 pt} + \setlength{\parsep}{0 pt} +}{ + \end{itemize} +} + + +% exclamation mark environment +% ---------------------------- +\newenvironment{important}{ + \vspace{1ex plus 1ex} + \begin{minipage}[c]{\textwidth} + + \begin{center} + \rule{0.99\textwidth}{2pt} + + \vspace{1ex} + + \begin{minipage}[c]{0.1 \textwidth} + {\Huge \bf \sf \textcircled{\Large !}} + \end{minipage} + \begin{minipage}[c]{0.85 \textwidth} + \begingroup\sf +}{ + \endgroup + \end{minipage} + + \vspace{1ex} + + \rule{0.99\textwidth}{2pt} + \end{center} + \end{minipage} + \vspace{1ex plus 1ex} +} + +\hyphenation{make Named Linux} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{document} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\newpage +\thispagestyle{empty} + +\begin{center} +{ +\Large \sf Robert~Schwebel + +\vspace{2 cm} + +\Huge \sf \textbf{The PTXdist Manual} +} + +\vspace{\fill} + +{ +\Large \sf \copyright \, 2004 by Pengutronix. All Rights Reserved. \\ +All kind of duplication other than explicitly allowed is prohibited. +} + +\end{center} + +\newpage + +% ----------------------------------------------------------------------------- +\markboth{\sffamily\small\upshape\bfseries Table of Contents}{\sffamily\small + \upshape\bfseries Table of Contents} +\markright{\sffamily\small Table of Contents} +\thispagestyle{headings} + +{ +\parskip0mm +\tableofcontents +} + +% ----------------------------------------------------------------------------- + +\part{Introduction} +\input{intro/embedded-linux.tex} +\input{intro/maintaining-userlands.tex} + +\part{End User Manual} +\input{user/building-blocks.tex} +\input{user/i386-generic.tex} +\input{user/running-make.tex} +\input{user/subtargets.tex} +%\input{user/config-system.tex} +%\input{user/toolchain-targets.tex} + +%\part{Developing with PTXdist} +%\input{devel/kconfig.tex} +%\input{devel/makefile-targets.tex} +%\input{devel/new-packages.tex} +%\input{devel/macros.tex} + +% ----------------------------------------------------------------------------- +% Follow Up Literature and Web Sites +% ----------------------------------------------------------------------------- + +% Here we have to set the sub chapter numbers manually !! + +\appendix +\part{Appendix} +\input{appendix/licenses.tex} +\input{appendix/releases.tex} +\begin{thebibliography}{99} +%\input{appendix/literature.tex} +%\input{appendix/www.tex} +%\input{appendix/companies.tex} +\end{thebibliography} +%\input{appendix/cd.tex} +%\input{appendix/help.tex} + + +\printindex + +\end{document} diff --git a/Documentation/manual/appendix/licenses.tex b/Documentation/manual/appendix/licenses.tex new file mode 100644 index 000000000..76ace96ef --- /dev/null +++ b/Documentation/manual/appendix/licenses.tex @@ -0,0 +1,345 @@ +\chapter{License: GPL} + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +% ---------------------------------------------------------------------------- + diff --git a/Documentation/manual/appendix/releases.tex b/Documentation/manual/appendix/releases.tex new file mode 100644 index 000000000..8251afe00 --- /dev/null +++ b/Documentation/manual/appendix/releases.tex @@ -0,0 +1,6 @@ +\chapter{Release History} + +\begin{itemize} +\item 20040222-1: Initial PTXdist manual release. Introduction and user + documentation written, developer documentation is still missing. +\end{itemize} diff --git a/Documentation/manual/devel/kconfig.tex b/Documentation/manual/devel/kconfig.tex new file mode 100644 index 000000000..5abc7e430 --- /dev/null +++ b/Documentation/manual/devel/kconfig.tex @@ -0,0 +1,4 @@ +% ---------------------------------------------------------------------------- +\chapter{KConfig} \label{chap:kconfig} +% ---------------------------------------------------------------------------- + diff --git a/Documentation/manual/devel/macros.tex b/Documentation/manual/devel/macros.tex new file mode 100644 index 000000000..1f39c0c0b --- /dev/null +++ b/Documentation/manual/devel/macros.tex @@ -0,0 +1,4 @@ +% ---------------------------------------------------------------------------- +\chapter{Macros} \label{chap:macros} +% ---------------------------------------------------------------------------- + diff --git a/Documentation/manual/devel/makefile-targets.tex b/Documentation/manual/devel/makefile-targets.tex new file mode 100644 index 000000000..f53d92be3 --- /dev/null +++ b/Documentation/manual/devel/makefile-targets.tex @@ -0,0 +1,4 @@ +% ---------------------------------------------------------------------------- +\chapter{Makefile Targets} \label{chap:makefile-targets} +% ---------------------------------------------------------------------------- + diff --git a/Documentation/manual/devel/new-packages.tex b/Documentation/manual/devel/new-packages.tex new file mode 100644 index 000000000..043077882 --- /dev/null +++ b/Documentation/manual/devel/new-packages.tex @@ -0,0 +1,4 @@ +% ---------------------------------------------------------------------------- +\chapter{Developing New Packages} \label{chap:new-packages} +% ---------------------------------------------------------------------------- + diff --git a/Documentation/manual/figures/menuconfig.png b/Documentation/manual/figures/menuconfig.png new file mode 100644 index 000000000..a1094aada Binary files /dev/null and b/Documentation/manual/figures/menuconfig.png differ diff --git a/Documentation/manual/intro/embedded-linux.tex b/Documentation/manual/intro/embedded-linux.tex new file mode 100644 index 000000000..c4e26569f --- /dev/null +++ b/Documentation/manual/intro/embedded-linux.tex @@ -0,0 +1,103 @@ +% ---------------------------------------------------------------------------- +\chapter{Embedded Linux} \label{chap:embedded-linux} +% ---------------------------------------------------------------------------- + +\begin{flushright} +\emph{ +If you treat your beta-testers as if they're \\ +your most valuable resource, they will respond \\ +by becoming your most valuable resource.\\ +} +\textsc{\small Eric S. Raymond} +\end{flushright} + +Once upon in time embedded systems didn't need operating systems. Things +have been so easy: all a developer needed was a good toolchain, +consisting of compilers and other development tools, probably an EPROM +burning device and things started working. After some time every +register of the CPU was known, a variety of library routines have been +developed and our brave developer was able to do his project with the +more and more well known system. The controllers had legacy interfaces +like RS232, i2c or SPI which connected them to the outside world and the +main difference between the controllers available on the marked was the +number of GPIO pins, UARTS and memory ressources. + +Over the time, things have changed. Hardware manufacturers have weakened +the border between microcontrollers --~devices meant to work in embedded +systems~-- and full blown microprocessors. Structures became much more +complicated: where our good old controllers had just some interrupts +with some small interrupt service routines we today need complicated +generic interrupt infrastructures, suitable for generic software +frameworks. Where we had some linearly mapped flash ROM and some data +RAM we today have multi-stage-pipeline architectures, memory management +units, virtual address spaces, on-chip-memory, caches and other +complicated stuff, which is not exactly what the embedded system +developer wants do every other day. + +Entering embedded operating systems. Although there are still some +processors out there (like the popular ARM7TDMI based SoCs) which can be +programmed the good old non-operating-system way, it is becomming more +and more difficult. On the other hand, legacy I/O interfaces like RS232 +are increasingly replaced by modern plug-and-play aware communication +channels: USB, FireWire (IEEE1394), Ethernet \& friends are more and +more directly being integrated into today's microcontroller hardware. +Whereas some of these interfaces can "`somehow"' be handled the old +controller-style way of writing software, the developer following this +way will not be able to address the security and performance issues +which come up with the modern network accessable devices. + +During the last years, this resulted in more and more of the small-scale +companies which developed little embedded operating system being pushed +out of the market. Nearly no small company is able to support all the +different interfaces, communication stacks, development tools and +security issues out there. New interfaces and -variants (like USB +on-the-go) are developed faster than operating system developers can +supply the software for them. This today results in a market +consolidation: only the largest commercial embedded operating system +supplyers will survive. + +Only the largest commercial...? There is one exception: when the same +situation came up in the "`mainstream"' computer market at the beginning +of the 1990ies, people started to develop an alternative to the large +commercial operating systems: Linux. Linux did never start with a +ready-to-use solution: people had a problem, searched for a solution but +didn't find one. Then they started to develop one themselves, often +several people did this in parallel, and in a huge community based +evolution mechanism the best solutions found their way into the Linux +kernel, which over the time formed one of the most reliable and +performant kernels available today. This "`develop-and-evolute"' +mechanism has shown it's effectiveness over and over again in the +server and desktop market today. + +Also for embedded systems Linux grew more and more popular. Studies have +shown that more than 70\% of the embedded developers are not satisfied +with a black box operating system: they want to adapt it to their needs, +to their special hardware situation (which most times is Just Different +than anything available). Embedded projects are even more variegated +than desktop- or server projects, due to the fact that there exist so +many different embedded processors with lots of peripherals out there. +Linux has evolved from a i386 only operating system to a kernel running +on nearly every modern 32 bit processor available today: x86, PowerPC, +ARM, MIPS, m68k, cris, Super-H etc. The kernel supplies a hardware +abstraction layer which lets our brave embedded developer once again +concentrate on his very special problem, not on handling neglibilities +like memory management. + +But Linux is only half of the story. Besides the kernel, a Linux based +embedded system consists of a "`Userland"': a filesystem, containing all +the small tools which form a small Unix system. Only the combination of +the kernel and a Userland let's the developer run "`normal"' processes +on his x86 development machine as well as on his embedded target. + +Whereas the mainstream developers were always able to use normal Linux +distributions like SuSE, RedHat, Mandrake or Debian as a base for their +applications, things are different for embedded systems. Due to the +restricted ressources these systems normally have, distributions had to +be small and should only contain that things which are needed for the +application. Additionally, they had to be auditable and reproducable: +Embedded developers usually want to know what's in their systems -- be +it that they have to support their software for a long time span +(something like 10-15 years are usual product lifetimes in automation +applications) or that they have such a special scenario that they have +to maintain their integrated source of their Userland themselves. +Entering PTXdist. diff --git a/Documentation/manual/intro/maintaining-userlands.tex b/Documentation/manual/intro/maintaining-userlands.tex new file mode 100644 index 000000000..15ce4b1f2 --- /dev/null +++ b/Documentation/manual/intro/maintaining-userlands.tex @@ -0,0 +1,108 @@ +% ---------------------------------------------------------------------------- +\chapter{Maintaining Userlands} \label{chap:userlands} +% ---------------------------------------------------------------------------- + +\begin{flushright} +\emph{ +Use the source, Luke!\\ +} +\textsc{\small Obi-Wan Kenobi} +\end{flushright} + +The idea for PTXdist came up when the people at Pengutronix had to +compile the userlands for customer projects over and over again. Nearly +no customer had the same requirements: one needed network tools like +\texttt{ifconfig}, servers like \texttt{thttpd} or \texttt{dhcpd}, +others needed tools for accessing displays, embedded web browsers or +other Human Machine Interface stuff. + +The systems most time were so different that the way of stripping down a +mainstream distribution did not work well: you simply cannot strip down +a Debian system small enough to fit into a 2~MB RAM and 2~MB Flash +system without destroying the whole idea behind the distribution. The +other way is to build a Userland from scratch: Linux distributions like +LFS follow this path, but users have to do every configuration and +compilation step one after the other, which is a time consuming and +errorprone way. + +What we basically needed when we started PTXdist was: +\begin{itemize} +\item A configuration frontend which lets the embedded developer just + select which components he wants to have in his Userland. The + configuration should be totally independend from the rest of the + system. +\item The system should be small at this time: no need to download + several tens of megabytes from the net, even before selecting what + would go into the image. +\item A set of rules, easily readable by every reasonably silled Unix + develper, which reads the configuration and defines how to + build a certain software packet, taking into account what the + user has selected during configuration. +\item A framework which makes it easy for a developer to add new packets + to the system when he needs something which is not yet integrated. +\item The whole thing should be Open Source like the Linux kernel and + the Userland software itself, as our customers wanted a completely + transparent, modificable and debuggable software framework, be it + the bootloader, the kernel or, finally, the Userland tools. +\item Last but not least, the whole system should be platform + independend, to build userland for whatever architecture the + user works with. +\end{itemize} + +When we looked around for existing solutions there was none that +fulfilled all these requirements: some where large beasts (like the +uClinux distribution), some had an interesting approach (like the +emDebian Project) but used the wrong tools (CML2 for configuration, +which is basically a dead project today), others had a great +infrastructure for the rules (like buildroot, part of the uClibc +project) but no configuration frontend usable by normal end users. So we +finally had a look at all the available projects, collected the best +ideas and started a new Open Source project: PTXdist. + +Over the last two years, PTXdist grew with the projects which have been +developed for Pengutronix' customers. PTXdist is still no distribution: +distributions are meant to just-work-out-of-the-box, which is simply not +possible for the multifaceted situations we have in embedded projects. +The idea behind PTXdist is more something like: + +\begin{important} +{\bf PTXdist is "`Executable Documentation"'. Write down what you +did once to make something work, in a well defined manner, and +implicitly don't forget it until you need it the next time.} +\end{important} + +When a Userland for a certain customer board is developed, the PTXdist +framework is used to document all the necessary steps to build the +binaries from the original sources. PTXdist defines which configuration +switches have to be selected, which tweaks have to be applied to buggy +upstream source trees and which are the commands which have to be +started in which order to build a working tree. + +At the end of a development project, the customer normally has a +standard configuration integrated in PTXdist which lets him build his +own Userland with \texttt{make~world}, he is able to work with the +framework and switch on and off things he wants to change himself. Some +customers have enough skills to send patches in case some randomly +switched on config button doesn't show the expected results, others use +Pengutronix' support services to integrate new packets into PTXdist or +fix problems which come up with configuration constellations which have +beed never tested before (with over 600 config entries there are $2^600$ +possible combinations -- it would take some time to test them all). + +And, of course, we managed to build a community around PTXdist, which +consists mainly of a mailing list on the PTXdist server. People outside +Pengutronix started to work with the system for their own project, which +is very important to make PTXdist more robust and test it in +constellations which have not yet been realized here. + +So when you start your next Embedded Linux project with PTXdist don't +expect it to be something "`finished"' -- it is as finished or +unfinished as the Linux kernel itself, which is just a collection of +software which has proven to be great in one or the other situation, and +which has been looked over by several people. The more people use +PTXdist for their projects, the more robust and the more feature rich it +becomes -- just like with the kernel. The power of Linux and PTXdist +come from it's Open Source nature and from people working together to +form an industry quality software framework -- you just have to join the +team! + diff --git a/Documentation/manual/user/building-blocks.tex b/Documentation/manual/user/building-blocks.tex new file mode 100644 index 000000000..2b51c9078 --- /dev/null +++ b/Documentation/manual/user/building-blocks.tex @@ -0,0 +1,138 @@ +% ---------------------------------------------------------------------------- +\chapter{Building Blocks of PTXdist} \label{chap:building-blocks} +% ---------------------------------------------------------------------------- + +\section*{The Big Picture} + +PTXdist is good for basically two tasks: compiling stuff for an embedded +system, which means to compile components which go into the +\texttt{root/} directory of the PTXdist tree, and compiling tools which +are needed on the development host to build other code for the target. + +\begin{important} +The PTXdist manual does consequently talk about two computers you +usually work with: one is the \emph{development host} -- this is the +normal PC you work on. The development host needs a generic Linux +distribution (for example Debian, SuSE, RedHat or Mandrake). The other +one is the \emph{embedded target}, sometimes also referenced as the +\emph{target}. The Target is usually an embedded device and may have +another processor architecture than your development host. +\end{important} + +% ----------------- +\begin{figure}[b] + \centerline{\includegraphics[width=0.99\textwidth]{figures/menuconfig}} + \caption{ + KConfig in menuconfig mode: select what you want in your + target. + \label{fig:menuconfig} + } +\end{figure} +% ----------------- + +Code for the host is being compiled with the distribution's native C +compiler (normally GCC), whereas you need a cross compiler to build code +for the target. We'll discuss later how you can get a cross compiler, +just in case you don't have one yet. + +Before we start digging deeper into PTXdist's internals let's have a +look at the building blocks the system consists of. The main building +blocks are: + +\begin{itemize} +\item The KConfig frontend (select what you want to have in your root + filesystem), and +\item A set of Makefiles (rules which contain what has to be done). +\end{itemize} + +The KConfig frontend is normally used by somebody who wants to configure +a \emph{selection} of programs which are later put into the root +filesystem of an embedded system; configuring mostly consists of +clicking on software components you want to install. Once you have a +working set of rules and a sane \emph{base} for your projects, you can +use the KConfig frontend to make your selection, without the need to do +further changes on a programming base. If you want to learn more about +how the KConfig system works, read section~\ref{chap:config-system}. +When you start working with PTXdist, somebody has normally already done +a more or less ready-to-use configuration. Check out which +configurations are available on your system: + +% ----------------- +\begin{code} +robert@himalia:~/work/cvs-rsc/ptxdist> make configs + +Available configs: +[...] +i386-generic-glibc_config: +[...] +toolchain-powerpc-405-linux_config: +toolchain-arm-linux-3.3.2_config: +toolchain-arm-linux-2.95_config: +[...] +\end{code} +% ----------------- + +As you can see here, your PTXdist tree does currently have targets named +\emph{i386-generic-glibc\_config}, +\emph{toolchain-powerpc-405-linux\_config}, +\emph{toolchain-arm-linux-3.3.2\_config}, +\emph{toolchain-arm-linux-2.95\_config}. According to the version you +are using you'll probably see more targets. The rules you see here are +so called \emph{config rules}. They all end in \emph{\_config} and their +task is to copy a pre-developed configuration into your toplevel +directory where it can be used to define what the next compiler run +generates. You can start one of these targets by running + +\begin{code} +robert@himalia:~/ptxdist> make _config +\end{code} + +while replacing \texttt{} by the name of your configuration target. + +% ----------------- +\begin{important} +After you run \texttt{make \_config} a predefined configuration +file, containing a set of to-be-installed applications, is copied into +your PTXdist directory. + +\vspace{1ex} + +Don't forget to run \texttt{make oldconfig} now! This is necessary to +make a configuration ready for running and also checks if your +configuration is consistent to the config system of your currently used +PTXdist version. +\end{important} +% ----------------- + +Now, you are ready for making it really happen. Until this moment, your +PTXdist tree does only contain what came from the archive; the next +steps the framework has to do is to get all the archives of the original +(\emph{upstream}) softare packets you need, extract them, prepare them +for compilation, put in the right configurations, run the cross compiler +(in case of tools for the target) or the host compiler (in case of host +tools) on them and, finally, install the compiled results into +appropriate places. + +We'll see later how all of these topics are done in detail, for now you +basically have to call \texttt{make world} to start the run. Take into +account that building a complete userland or toolchain does take some +time, so if your computer runs for several hours it might be just fine. + +The result of the compiler run is a set of installed programs in their +respective places; if you have configured PTXdist for building a +userland you'll find your root filesystem in the \texttt{root/} +directory now, ready for being mounted to your target via NFS or being +flashed into some flash filesystem. + +If you ever want to cleanup your PTXdist tree, just enter \texttt{make +distclean} at the shell prompt. The distclean target brings your PTXdist +tree back into the state where you have started, which means that you +can safely start the whole thing again. If you don't want to lose your +configuration, enter \texttt{make clean} instead. This also cleans up +the build directories, but leaves the configuration intact. + +It is also possible to clean out single packets, which is helpful when +you want to change the configuration for one software component, but +don't want to recompile the whole system. We'll discuss later in +chapter~\ref{} how this is done. + diff --git a/Documentation/manual/user/config-system.tex b/Documentation/manual/user/config-system.tex new file mode 100644 index 000000000..bcef1a72d --- /dev/null +++ b/Documentation/manual/user/config-system.tex @@ -0,0 +1,4 @@ +% ---------------------------------------------------------------------------- +\chapter{The Config System} \label{chap:config-system} +% ---------------------------------------------------------------------------- + diff --git a/Documentation/manual/user/i386-generic.tex b/Documentation/manual/user/i386-generic.tex new file mode 100644 index 000000000..4e281fa83 --- /dev/null +++ b/Documentation/manual/user/i386-generic.tex @@ -0,0 +1,115 @@ +% ---------------------------------------------------------------------------- +\chapter{The i386-generic-glibc Target} \label{chap:i386-generic} +% ---------------------------------------------------------------------------- + +Now, we have enough theoretical background to try out a first example. +The PTXdist developers have prepared a generic configuration which can +be run on every Intel 386 compatible PC that might happen to go to seed +in a dark corner of your lab. Consisting of "normal", non-embedded, +hardware, it can be used as an ideal starting point for your first +PTXdist experiments. Contrary to a real target, a normal PC has the +advantage of having standard interfaces, such as a keyboard or a video +card with a monitor, which makes it easier to find out why something +goes wrong in case of a problem. + +Select the generic target by entering at your bash command line + +\begin{code} +robert@himalia:~/ptxdist> make i386-generic-glibc_config +copying i386-generic-glibc configuration +robert@himalia:~/ptxdist> +\end{code} + +\begin{important} +If you have played around with the PTXdist tree you are working in +before, don't forget to run \texttt{make distclean} before this command. +Whenever you have the impression that something is strange with +your tree, distclean it and start from a well-known starting +point. +\end{important} + +PTXdist needs a directory where it can install it's host tools. By +default, this directory is set to \texttt{/tmp/ptxdist-local-generic}, +which should not collide with any other program. Please check if this +directory is empty or non-existent on your host, to avoid conficts with +old stuff. When there is old stuff laying around in this directory, +either delete it (\texttt{rm -fr /tmp/ptxdist-local-generic}) after +carefully checking if you \emph{really} delete it, or chose another +directory for your host tools (see chapter~\ref{} to find out how to do +this). We refer to the directory containing the host tools as the +\texttt{PTXCONF\_PREFIX} directory from now on, as this is the name the +PTXdist build system uses internally. + +We assume everything is configured correctly now and run \texttt{make +oldconfig} to evaluate and process the new configuration now. You should +see some compiler output messages now, a bunch of questions are printed +out, including their respective answers, and the system should come back +to the shell command line prompt without stopping. + +\begin{important} +If PTXdist stops while running \texttt{make oldconfig} and asks stupid +questions, the config file you are using doen't fit the currently used +PTXdist version. This probably means that it was not updated correctly +by the maintainer when he made the last release; write a mail with a bug +report to the PTXdist mailing list. +\end{important} + +Now, you need two things: first of all, either a CD with all sources +being necessary for your target, or an internet connection which lets +your development host get all the source packages from the net. As we +already discussed, PTXdist decides during runtime which packages are +needed to compile your root filesystem: the decision is based on what +the currently used configuration has selected and on implicit +dependencies which are resolved automatically. + +In case you choose the internet connection variant you don't have to do +anything and can start building, as described below. When you want to +avoid the source packet downloads, copy all the source archives from +your CD to the \texttt{src/} directory of the PTXdist tree. While +running PTXdist the system tries to extract packages when they are about +to being processed; when they are not available they are transferred via +HTTP or FTP connection, so when you copy everything to the \texttt{src/} +directory no archives are transferred. If you forgot one or the other +packet it is no problem, it just is pulled from the net in that case. +Take this into account when you have a low-bandwith or pay-per-volume +line for your internet traffic. + +We now start the main compiler run: + +\begin{code} +robert@himalia:~/ptxdist> make world +\end{code} + +This triggers the whole mechanism and if nothing goes wrong you get a +ready-to-use root filesystem for the embedded system after a while. If +you want to have more information about what happens during the build, +if you want to have a logfile for the case when something goes wrong and +if you want to find out how long the build-run took to complete use the +following line: + +\begin{code} +robert@himalia:~/ptxdist> time make world 2>&1 | tee logfile +\end{code} + +The \texttt{time} command prints out the time the whole thing took, +until control comes back to the command line. With \texttt{2>\&1} you +redirect all the stderr-output to stdout, which is afterwards fed to the +\texttt{tee} command, so all the output messages are not only printed to +the terminal but also logged in \texttt{logfile}. In case of an error +\texttt{logfile} may contain useful information about what went wrong. + +If everything has completed \texttt{root/} does contain the target's +root filesystem. As the \emph{i386-generic-glibc} target was developed +for the normal Intel architecture it can now be directly tested: + +\begin{code} +root@himalia:/home/robert/ptxdist> chroot root/ /bin/sh +\end{code} + +Note that the \texttt{chroot} command can only be executed when being +the root user. It locally changes the root path to the \texttt{root/} +directory for the target and executes, already from this new point of +view, the given binary (\texttt{/bin/sh} in this case). If you see a +prompt after that everything is ok: you just changed root into your new +self made "embedded system emulator". + diff --git a/Documentation/manual/user/running-make.tex b/Documentation/manual/user/running-make.tex new file mode 100644 index 000000000..c12600606 --- /dev/null +++ b/Documentation/manual/user/running-make.tex @@ -0,0 +1,121 @@ +% ---------------------------------------------------------------------------- +\chapter{Running Make} \label{chap:running-make} +% ---------------------------------------------------------------------------- + +After having completed the first PTXdist example we now want to have a +more detailed look at the different Makefile targets. A brief overview +of the possibilities is printed out when just running \texttt{make} +without any further options: + +\begin{code} +robert@himalia:~/work/cvs-rsc/ptxdist> make + +PTXdist - Pengutronix Distribution Build System + +Syntax: + + make menuconfig Configure the whole system + + make get Download (most) of the needed packets + make extract Extract all needed archives + make prepare Prepare the configured system + for compilation + make compile Compile the packages + make install Install to rootdirectory + make clean Remove everything but local/ + make rootclean Remove root directory contents + make distclean Clean everything + + make world Make-everything-and-be-happy + +Some 'helpful' targets: + + make virtual-xchain_install build the toolchain only + make archive-toolchain dito, but do also create a tarball + make configs show predefined configs + +[...] + +\end{code} + +To understand how these targets work, let's do a short excursion to the +mechanism of Makefiles. As Makefiles may be a little bit unfamiliar for +you when you have not been writing Unix programs before we will explain +how they work in a short example. + +Makefiles are a generic way to define what to do to define a certain +\emph{target}: a target is something --~usually a file~-- being built by +executing a rule which consists of some commands. Targets can not only +have rules, they also have \emph{dependencies}. A dependency defines +that, before the current target can be built, first the dependency has +to be fulfilled. + +Let's for example have a look at this little Makefile: +\begin{code} +all: baz + +foo: foo.src + generate foo from foo.src + +bar: bar.src + generate bar from bar.src + +baz: foo bar + link foo and bar together to create baz +\end{code} + +It defines three "real" targets: \texttt{foo}, \texttt{bar} and +\texttt{baz}. \texttt{foo} is created from \texttt{foo.src} by using the +rule \texttt{generate foo from foo.src}, the same for \texttt{bar}. +\texttt{foo} depends on \texttt{foo.src} and \texttt{bar} on +\texttt{bar.src}, so the target is recreated by the rule whenever the +dependency is newer than the target itself, which is usually the case +when somebody has changed the dependend file. \texttt{baz} depends on +\texttt{foo} and \texttt{bar}. The last target, \texttt{all}, is just +used as an alias. When somebody types \texttt{make} in the directory +containing this Makefile, the first target is executed, which means in +our case that \texttt{make} tries to create target \texttt{baz}. + +Think about what happens when somebody has changed \texttt{foo.src} and +\texttt{bar.src}: \texttt{make} wants to build \texttt{baz}, which needs +\texttt{foo}. \texttt{make} notices that \texttt{foo.src} was modified +and recreates \texttt{foo} from \texttt{foo.src}, using the appropriate +rule. Now \texttt{foo} is there, so the first dependency for +\texttt{baz} is fulfilled and \texttt{make} wants to have the dependency +\texttt{bar}. \texttt{bar.src} was modified, so \texttt{bar} is +recreated with it's rule. This means that all dependencies for +\texttt{baz} have been fulfilled, so \texttt{make} runs the rule to link +\texttt{foo} and \texttt{bar} together into \texttt{baz}. + +As you may notice, it is possible to split complicated inter-target +dependencies into easy-to-read target/dependency/rule sets. Makefiles +make it possible to reduce all the complicated what-happens-when cases +to simple targets. That's why the Makefile mechanism was chosen as a +base for PTXdist. + +The most important targets listed above are these: + +\paragraph{make menuconfig:} Configure the whole system. This starts the +text based Kconfig frontend (more on this in chapter~\ref{}). + +\paragraph{make world:} Build the whole system. This is normally what +you do to build a preconfigured configuration. + +\paragraph{clean:} Clean up all build stuff; each packet which is being +compiled extracts it's source code and sometimes also a separate build +directory in PTXdist's \texttt{build/} directory. During the +\texttt{clean} stage this is removed. + +\paragraph{rootclean:} Remove the contents of the target's root +directory, rediding in \texttt{root/}. The sequence \texttt{make +rootclean \&\& make world} can often be used if you have somehow +corrupted your target root directory and want to have it recreated from +the already compiled sources. + +\paragraph{distclean:} Brings the whole tree back into it's state after +it was freshly extracted from the PTXdist archive. Helpful when you want +to start from the beginning or if you want to make patches against a +cleaned up tree. + +\paragraph{configs:} Show which default configurations are available. + diff --git a/Documentation/manual/user/subtargets.tex b/Documentation/manual/user/subtargets.tex new file mode 100644 index 000000000..37064adf7 --- /dev/null +++ b/Documentation/manual/user/subtargets.tex @@ -0,0 +1,81 @@ +% ---------------------------------------------------------------------------- +\chapter{Subtargets} \label{chap:subtargets} +% ---------------------------------------------------------------------------- + +Compiling a whole configuration in one step is usually what is done +when, for example, a board support package for an embedded PC is rolled +out. In this case, \texttt{make world} should simply work and spit out a +ready to run root filesystem for the embedded target. But most of the +time working with PTXdist you won't build complete runs but work on the +integration of a single software packet or on your special target +integration. In theses situations, running the whole \texttt{make clean +\&\& make world} sequence is time consuming and boring. + +Let's have a more in-detail look at the single targets each PTXdist +ruleset for a software packet consists of. This hopefully brings more +light into the darkness of what happens behind the scenes and what has +to be done to recompile single stages. + +Each packet's rule file, living in \texttt{rules/somepacket.make}, is +just a simple Makefile. There are several rules which targets this +Makefile must contain: +% +\begin{itemize} +\setlength{\itemsep}{0pt} +\item \textbf{get:} Get the source archives for a packet. +\item \textbf{extract:} Extract the archive and, if necessary, apply + some patches. +\item \textbf{prepare:} Run the configure part of the software package. +\item \textbf{compile:} Compile or cross-compile. +\item \textbf{install:} Install host-side tools build by \emph{compile} + into the PTXDIST\_PREFIX directory. +\item \textbf{targetinstall:} Install the target-side programs into the + \texttt{root/} directory. +\end{itemize} +% +For each target there is a corresponding so called \emph{statefile} in +\texttt{state/} which is touched by the framework when the target was +called. \emph{Touching} means that the file gets the current time as +it's time stamp. The state files are used as dependencies for other +packages. + +Assume we have a packet called \texttt{gargelpu}. It will have it's +rules in \texttt{rules/gargelpu.make}, which is a Makefile containing +targets to create +% +\begin{itemize} +\setlength{\itemsep}{0pt} +\item \texttt{state/gargelpu.get}, +\item \texttt{state/gargelpu.extract}, +\item \texttt{state/gargelpu.prepare}, +\item \texttt{state/gargelpu.compile}, +\item \texttt{state/gargelpu.install} and +\item \texttt{state/gargelpu.targetinstall}. +\end{itemize} +% +To force recreation of a target and all targets which depend on it you +can remove the state file and run \texttt{make world} again. Also, to +force recreation of a single sub-target you can delete the statefile, +for example \texttt{state/gargelpu.compile}, and run \texttt{make +state/gargelpu.compile} again. + +As these target names are a little bit longish to type there are +convenience targets which define abbreviated names. Normally these ones +are used during the work on PTXdist when you want to recreate certain +sub-targets: +% +\begin{itemize} +\setlength{\itemsep}{0pt} +\item \texttt{gargelpu\_get} +\item \texttt{gargelpu\_extract} +\item \texttt{gargelpu\_prepare} +\item \texttt{gargelpu\_compile} +\item \texttt{gargelpu\_install} and +\item \texttt{gargelpu\_targetinstall} +\end{itemize} + +Like above, invalidating a sub-target is done by just removing the state +file, e.g. \texttt{state/gargelpu.compile}, and running \texttt{make +gargelpu\_compile}. Note the underscore in place of the dot -- +\texttt{make} is unable to accept dots here. + diff --git a/Documentation/manual/user/toolchain-targets.tex b/Documentation/manual/user/toolchain-targets.tex new file mode 100644 index 000000000..5766626d3 --- /dev/null +++ b/Documentation/manual/user/toolchain-targets.tex @@ -0,0 +1,4 @@ +% ---------------------------------------------------------------------------- +\chapter{Toolchain Targets} \label{chap:toolchain-targets} +% ---------------------------------------------------------------------------- + -- cgit v1.2.3