[med-svn] r1264 - trunk/community/website/docs

Sat Feb 2 18:18:49 UTC 2008

Author: hanska-guest
Date: 2008-02-02 18:18:49 +0000 (Sat, 02 Feb 2008)
New Revision: 1264

Modified:
   trunk/community/website/docs/policy.tex
Log:
Adding some more content


Modified: trunk/community/website/docs/policy.tex
===================================================================

--- trunk/community/website/docs/policy.tex	2008-02-02 17:23:00 UTC (rev 1263)
+++ trunk/community/website/docs/policy.tex	2008-02-02 18:18:49 UTC (rev 1264)
@@ -43,17 +43,14 @@
 \HRule \\[1.5cm]
 \begin{minipage}[t]{0.4\textwidth}
 \begin{flushleft}
-\large \emph{Author:}\\
+\large \emph{Authors:}\\
 David \textsc{Paleino}
 \end{flushleft}
 \end{minipage}
 \begin{minipage}[t]{0.4\textwidth}
 \begin{flushright}
 \large \emph{Supervisors:}\\
-Nelson A. \textsc{de Oliveira} \\
-Charles \textsc{Plessy} \\
-Andreas \textsc{Tille} \\
-Foo \textsc{Bar} \\
+Andreas \textsc{Tille}
 \end{flushright}
 \end{minipage}
 \rule[-5mm]{\linewidth}{0.5mm}
@@ -174,7 +171,7 @@
 alias svn-bt='svn-buildpackage --svn-tag -rfakeroot'
 \end{verbatim}
 You're ready now to checkout the sources (see the proper section). \\ \\
-Once done, you're ready to do the work. First, cd to the \texttt{trunk} directory, and download the upstream sources (if there is a debian/watch file):
+Once done, you're ready to do the work. First, cd to the \texttt{trunk} directory, and download the upstream sources (if there is a debian\slash{watch} file):
 \begin{verbatim}
 echo "origDir=.." >> .svn/deb-layout && uscan --force-download
 \end{verbatim}
@@ -194,9 +191,9 @@
 \begin{verbatim}
 svn-buildpackage --svn-tag
 \end{verbatim}
-You can tag this package also retroactively. A first step, creating the \texttt{tags/} directory, can be achieved in two ways:
+You can tag this package also retroactively. A first step, creating the \texttt{tags\slash} directory, can be achieved in two ways:
 \begin{itemize}
-\item create it locally (it is a sibling of \texttt{trunk/}), and commit:
+\item create it locally (it is a sibling of \texttt{trunk\slash}), and commit:
 \begin{verbatim}
 svn mkdir tags
 svn commit
@@ -206,24 +203,17 @@
 svn mkdir svn+ssh://user@svn.debian.org/svn/debian-med/trunk/packages/<package>/tags
 \end{verbatim}
 \end{itemize}
-After the \texttt{tags/} directory has been created, you're ready to tag the package:
+After the \texttt{tags\slash} directory has been created, you're ready to tag the package:
 \begin{verbatim}
 svn-buildpackage --svn-tag-only --svn-no-autodch
 \end{verbatim}
-(\texttt{--svn-autodch} avoids \texttt{debian/changelog} to be marked as \texttt{UNRELEASED}).
+(\texttt{--svn-no-autodch} avoids \texttt{debian\slash{changelog}} to be marked as \texttt{UNRELEASED}).
 \subsection{Handling patches}
-Often happens that the upstream code doesn't fit well into the Debian distribution: be this wrong paths, missing features, anything that implies editing the source files. When you directly edit upstream's source files, your changes will be put into a \texttt{.diff.gz} file, which should instead contain only \texttt{debian/}. Because of this, it's best using a \emph{patch handling system}. The most known are \texttt{dpatch} and \texttt{quilt}.
-\subsubsection{Using \texttt{dpatch}}
-\paragraph{Creating a patch}
-\texttt{dpatch-edit-patch}\\
-\paragraph{Applying and unapplying patches}
-\texttt{apply(-all)}, \texttt{unapply(-all)}, \texttt{status}\\
-\paragraph{Editing a patch}
-\texttt{dpatch-edit-patch}\\
-
+Often happens that the upstream code doesn't fit well into the Debian distribution: be this wrong paths, missing features, anything that implies editing the source files. When you directly edit upstream's source files, your changes will be put into a \texttt{.diff.gz} file, which should instead contain only \texttt{debian\slash}. Because of this, it's best using a \emph{patch handling system} which keeps patches under the \texttt{debian\slash} directory. \\
+The most known are \texttt{quilt} and \texttt{dpatch}. Please don't use any other patch system in Debian-Med, unless absolutely necessary.
 \subsubsection{Using \texttt{quilt}}
-Using \texttt{quilt} is rather easy (easier than \texttt{dpatch}, I'd say). \\
-First, make sure you have correctly setup quilt: open \texttt{.quiltrc} in your home directory (create it if you don't have one), and make sure it looks like this:
+Using \texttt{quilt} is rather easy. \\
+First, make sure you have correctly setup \texttt{quilt}: open \texttt{.quiltrc} in your home directory (create it if you don't have one), and make sure it looks like this:
 \begin{verbatim}
 QUILT_DIFF_ARGS="--no-timestamps --no-index"
 QUILT_REFRESH_ARGS="--no-timestamps --no-index"
@@ -237,7 +227,7 @@
 \begin{verbatim}
 quilt new <patch_name>.patch
 \end{verbatim}
-This will create (if it doesn't exist yet) a \texttt{debian/patches/series} file, which contains all the patches to be applied by quilt. Moreover, the new patch is also the \emph{topmost} (the currently applied). \\ \\
+This will create (if it doesn't exist yet) a \texttt{debian\slash{patches}\slash{series}} file, which contains all the patches to be applied by quilt. Moreover, the new patch is also the \emph{topmost} (the currently applied). \\ \\
 Now start editing files, with:
 \begin{verbatim}
 quilt edit <file>
@@ -246,14 +236,14 @@
 \begin{verbatim}
 quilt refresh
 \end{verbatim}
-This will compare the noted state of the edited files with the current state, and will produce a patch in \texttt{debian/patches}. Remember: the patch is currently \textbf{applied} (you can check this with \texttt{quilt applied}).
+This will compare the noted state of the edited files with the current state, and will produce a patch in \texttt{debian\slash{patches}}. Remember: the patch is currently \textbf{applied} (you can check this with \texttt{quilt applied}).
 \paragraph{Applying and unapplying patches}
 \texttt{push}, \texttt{pop}, \texttt{applied}, \texttt{unapplied}\\
 Just two easy commands to do the job: \\ \\
 \texttt{quilt pop} will unapply the topmost patch. \\
 \texttt{quilt push} will apply the next patch in \texttt{debian/patches/series}. \\
 You can just add a ``-a'' flag to the commands above, to respectively apply/unapply \textbf{all} patches in the series. \\ \\
-You can check which patches are applied / unapplied with, respectively, \texttt{quilt applied} and \texttt{quilt unapplied}.
+You can check which patches are applied\slash{unapplied} with, respectively, \texttt{quilt applied} and \texttt{quilt unapplied}.
 \paragraph{Editing patches}
 \texttt{push}, \texttt{pop}, \texttt{edit}, \texttt{refresh}\\
 To edit a patch, first make it the topmost:
@@ -271,11 +261,40 @@
 \paragraph{Other commands}
 .\\
 Please see \texttt{man 1 quilt} to have a comprehensive list of commands.
-\subsubsection{Integration in the build process}
-TODO:
+\paragraph{Integration in the build process}
+Add in the very first part of \texttt{debian\slash{rules}} (i.e. \textit{before} the targets), the line:
 \begin{verbatim}
-include /usr/share/{quilt,dpatch}/{quilt,dpatch}.make
+include /usr/share/quilt/quilt.make
 \end{verbatim}
-\texttt{\$(QUILT\_STAMPFN)}
+Remember to add the needed dependencies to \texttt{Makefile}'s targets:
+\begin{verbatim}
 ...
+build: patch build-stamp
+build-stamp: configure
+...
+\end{verbatim}
+This kind of dependency will ensure that if you also patch the build system, you get a working \textit{patched} build process. Please don't also put \textit{configure} as a dependency of \texttt{build} (leave it in \texttt{build-stamp}): that may cause problems during parallel buildings (i.e. the \texttt{-j} flag of \texttt{make}).\\
+Now add a dependency to the clean target:
+\begin{verbatim}
+...
+clean: unpatch
+...
+\end{verbatim}
+If you've also patched the build system, using upstream's \texttt{clean} target might fail. This is what you should do:
+\begin{verbatim}
+...
+clean: clean-patched unpatch
+clean-patched:
+...
+\end{verbatim}
+Obviously, you could always use an approach like this, but it's an useless complication if you don't patch the build system, and you should keep \texttt{debian\slash{rules}} the simplest you can.
+\subsubsection{Using \texttt{dpatch}}
+\paragraph{Creating a patch}
+\texttt{dpatch-edit-patch}\\
+\paragraph{Applying and unapplying patches}
+\texttt{apply(-all)}, \texttt{unapply(-all)}, \texttt{status}\\
+\paragraph{Editing a patch}
+\texttt{dpatch-edit-patch}
+\paragraph{Integration in the build process}
+Follow the instructions for \texttt{quilt} and adapt the path of inclusion to \texttt{\slash{usr}\slash{share}\slash{dpatch}\slash{dpatch.make}}.
 \end{document}


