1.1 --- a/docs/0 - Table of content.txt Sat Aug 14 16:37:11 2010 +0200
1.2 +++ b/docs/0 - Table of content.txt Sat Aug 14 20:26:23 2010 +0200
1.3 @@ -54,3 +54,4 @@
1.4 C- Misc. tutorials
1.5 - Using crosstool-NG on FreeBSD (and other *BSD)
1.6 - Using crosstool-NG on MacOS-X
1.7 + - Using Mercurial to hack crosstool-NG
2.1 --- a/docs/7 - Contributing to crosstool-NG.txt Sat Aug 14 16:37:11 2010 +0200
2.2 +++ b/docs/7 - Contributing to crosstool-NG.txt Sat Aug 14 20:26:23 2010 +0200
2.3 @@ -29,198 +29,5 @@
2.4 12, of your favourite Linux kernel source tree.
2.5
2.6
2.7 -How to Use Mercurial |
2.8 ----------------------+
2.9 -
2.10 For larger or more frequent contributions, mercurial should be used.
2.11 -
2.12 -PREREQUISITES:
2.13 -
2.14 -Configuring Mercurial:
2.15 - You need mercurial with the following extensions:
2.16 - - mq : http://mercurial.selenic.com/wiki/MqExtension
2.17 - - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
2.18 - Usually, these two extensions are already part of the installation package.
2.19 - The mq extension maintains a separate queue of your local changes
2.20 - that you can change at any later time.
2.21 - With the patchbomb extension you can email those patches directly
2.22 - from your local repo.
2.23 -
2.24 - Your configuration file for mercurial, e.g. ~/.hgrc should contain
2.25 - at least the following sections (but have a look at `man hgrc`):
2.26 - # ---
2.27 - [email]
2.28 - # configure sending patches directly via Mercurial
2.29 - from = "Your Name" <your@email.address>
2.30 - # How to send email:
2.31 - method = smtp
2.32 -
2.33 - [smtp]
2.34 - # SMTP configuration (only for method=smtp)
2.35 - host = localhost
2.36 - tls = true
2.37 - username =
2.38 - password =
2.39 -
2.40 - [extensions]
2.41 - # The following lines enable the two extensions:
2.42 - hgext.mq =
2.43 - hgext.patchbomb =
2.44 - # ----
2.45 -
2.46 -Create your local repository as a clone:
2.47 - hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
2.48 -
2.49 -Setting up the mq extension in your local copy:
2.50 - cd crosstool-ng
2.51 - hg qinit
2.52 -
2.53 -
2.54 -CREATING PATCHES:
2.55 -
2.56 -Recording your changes in the patch queue maintained by mq:
2.57 - # First, create a new patch entry in the patch queue:
2.58 - hg qnew -D -U -e short_patch_name1
2.59 - <edit patch description as commit message (see below for an example)>
2.60 -
2.61 - <now edit the ct-ng sources and check them>
2.62 -
2.63 - # if you execute `hg status` here, your modifications of the working
2.64 - # copy should show up.
2.65 -
2.66 - # Now the following command takes your modifications from the working copy
2.67 - # into the patch entry
2.68 - hg qrefresh -D [-e]
2.69 - <reedit patch description [-e] if desired>
2.70 -
2.71 - # Now your changes are recorded, and `hg status` should show a clean
2.72 - # working copy
2.73 -
2.74 -Repeat the above steps for all your modifications.
2.75 -The command `hg qseries` informs you about the content of your patch queue.
2.76 -
2.77 -
2.78 -CONTRIBUTING YOUR PATCHES:
2.79 -
2.80 -Once you are satisfied with your patch series, you can (you should!)
2.81 -contribute them back to upstream.
2.82 -This is easily done using the `hg email` command.
2.83 -
2.84 -`hg email` sends your new changesets to a specified list of recipients,
2.85 -each patch in its own email, all ordered in the way you entered them (oldest
2.86 -first). The command line flag --outgoing selects all changesets that are in
2.87 -your local but not yet in the upstream repository. Here, these are exactly
2.88 -the ones you entered into your local patch queue in the section above, so
2.89 ---outgoing is what you want.
2.90 -
2.91 -Each email gets the subject set to: "[PATCH x of n] <series summary>"
2.92 -where 'x' is the serial number in the email series, and 'n' is the total number
2.93 -of patches in the series. The body of the email is the complete patch, plus
2.94 -a handful of metadata, that helps properly apply the patch, keeping the log
2.95 -message, attribution and date, tracking file changes (move, delete, modes...)
2.96 -
2.97 -`hg email` also threads all outgoing patch emails below an introductory
2.98 -message. You should use the introductory message (command line flag --intro)
2.99 -to describe the scope and motivation for the whole patch series. The subject
2.100 -for the introductory message gets set to: "[PATCH 0 of n] <series summary>"
2.101 -and you get the chance to set the <series summary>.
2.102 -
2.103 -Here is a sample `hg email` complete command line:
2.104 -Note: replace " (at) " with "@"
2.105 -
2.106 - hg email --outgoing --intro \
2.107 - --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>' \
2.108 - --cc 'crossgcc (at) sourceware.org'
2.109 -
2.110 - # It then opens an editor and lets you enter the subject
2.111 - # and the body for the introductory message.
2.112 -
2.113 -Use `hg email` with the additional command line switch -n to
2.114 -first have a look at the email(s) without actually sending them.
2.115 -
2.116 -
2.117 -MAINTAINING YOUR PATCHES:
2.118 -
2.119 -When the patches are refined by discussing them on the mailing list,
2.120 -you may want to finalize and resend them.
2.121 -
2.122 -The mq extension has the idiosyncrasy of imposing a stack onto the queue:
2.123 -You can always reedit/refresh only the patch on top of stack.
2.124 -The queue consists of applied and unapplied patches
2.125 -(if you reached here via the above steps, all of your patches are applied),
2.126 -where the 'stack' consists of the applied patches, and 'top of stack'
2.127 -is the latest applied patch.
2.128 -
2.129 -The following output of `hg qseries` is now used as an example:
2.130 - 0 A short_patch_name1
2.131 - 1 A short_patch_name2
2.132 - 2 A short_patch_name3
2.133 - 3 A short_patch_name4
2.134 -
2.135 -You are now able to edit patch 'short_patch_name4' (which is top of stack):
2.136 - <Edit the sources>
2.137 - # and execute again
2.138 - hg qrefresh -D [-e]
2.139 - <and optionally [-e] reedit the commit message>
2.140 -
2.141 -If you want to edit e.g. patch short_patch_name2, you have to modify
2.142 -mq's stack so this patch gets top of stack.
2.143 -For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
2.144 -
2.145 - hg qgoto short_patch_name2
2.146 - # The patch queue should now look like
2.147 - hg qseries
2.148 - 0 A short_patch_name1
2.149 - 1 A short_patch_name2
2.150 - 2 U short_patch_name3
2.151 - 3 U short_patch_name4
2.152 - # so patch # 1 (short_patch_name2) is top of stack.
2.153 - <now reedit the sources for short_patch_name2>
2.154 - # and execute again
2.155 - hg qrefresh -D [-e]
2.156 - <and optionally [-e] reedit the commit message>
2.157 - # the following command reapplies the now unapplied two patches:
2.158 - hg qpush -a
2.159 - # you can also use `hg qgoto short_patch_name4` to get there again.
2.160 -
2.161 -
2.162 -RESENDING YOUR REEDITED PATCHES:
2.163 -
2.164 -By mailing list policy, please resend your complete patch series.
2.165 ---> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
2.166 -
2.167 -
2.168 -SYNCING WITH UPSTREAM AGAIN:
2.169 -
2.170 -You can sync your repo with upstream at any time by executing
2.171 - # first unapply all your patches:
2.172 - hg qpop -a
2.173 - # next fetch new changesets from upstream
2.174 - hg pull
2.175 - # then update your working copy
2.176 - hg up
2.177 - # optionally remove already upstream integrated patches (see below)
2.178 - hg qdelete <short_name_of_already_applied_patch>
2.179 - # and reapply your patches if any non upstream-integrated left (but see below)
2.180 - hg qpush -a
2.181 -
2.182 -Eventually, your patches get included into the upstream repository
2.183 -which you initially cloned.
2.184 -In this case, before executing the hg qpush -a from above
2.185 -you should manually "hg qdelete" the patches that are already integrated upstream.
2.186 -
2.187 -
2.188 -HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
2.189 -
2.190 -Commit messages should look like (without leading pipes):
2.191 - |component: short, one-line description
2.192 - |
2.193 - |optional longer description
2.194 - |on multiple lines if needed
2.195 -
2.196 -Here is an example commit message (see revision a53a5e1d61db):
2.197 - |comp-libs/cloog: fix building
2.198 - |
2.199 - |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
2.200 - |For any later versions, the directory name does have the version, such as
2.201 - |cloog-ppl-0.15.4.
2.202 +There is a nice, complete and step-by-step tutorial in section 'C'.
3.1 --- a/docs/C - Misc. tutorials.txt Sat Aug 14 16:37:11 2010 +0200
3.2 +++ b/docs/C - Misc. tutorials.txt Sat Aug 14 20:26:23 2010 +0200
3.3 @@ -91,3 +91,200 @@
3.4 before executing ct-ng build.
3.5 See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html
3.6 as an explanation.
3.7 +
3.8 +
3.9 +Using Mercurial to hack crosstool-NG |
3.10 +-------------------------------------+
3.11 +
3.12 +Contributed by: Titus von Boxberg
3.13 +
3.14 +PREREQUISITES:
3.15 +
3.16 +Configuring Mercurial:
3.17 + You need mercurial with the following extensions:
3.18 + - mq : http://mercurial.selenic.com/wiki/MqExtension
3.19 + - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
3.20 + Usually, these two extensions are already part of the installation package.
3.21 + The mq extension maintains a separate queue of your local changes
3.22 + that you can change at any later time.
3.23 + With the patchbomb extension you can email those patches directly
3.24 + from your local repo.
3.25 +
3.26 + Your configuration file for mercurial, e.g. ~/.hgrc should contain
3.27 + at least the following sections (but have a look at `man hgrc`):
3.28 + # ---
3.29 + [email]
3.30 + # configure sending patches directly via Mercurial
3.31 + from = "Your Name" <your@email.address>
3.32 + # How to send email:
3.33 + method = smtp
3.34 +
3.35 + [smtp]
3.36 + # SMTP configuration (only for method=smtp)
3.37 + host = localhost
3.38 + tls = true
3.39 + username =
3.40 + password =
3.41 +
3.42 + [extensions]
3.43 + # The following lines enable the two extensions:
3.44 + hgext.mq =
3.45 + hgext.patchbomb =
3.46 + # ----
3.47 +
3.48 +Create your local repository as a clone:
3.49 + hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
3.50 +
3.51 +Setting up the mq extension in your local copy:
3.52 + cd crosstool-ng
3.53 + hg qinit
3.54 +
3.55 +
3.56 +CREATING PATCHES:
3.57 +
3.58 +Recording your changes in the patch queue maintained by mq:
3.59 + # First, create a new patch entry in the patch queue:
3.60 + hg qnew -D -U -e short_patch_name1
3.61 + <edit patch description as commit message (see below for an example)>
3.62 +
3.63 + <now edit the ct-ng sources and check them>
3.64 +
3.65 + # if you execute `hg status` here, your modifications of the working
3.66 + # copy should show up.
3.67 +
3.68 + # Now the following command takes your modifications from the working copy
3.69 + # into the patch entry
3.70 + hg qrefresh -D [-e]
3.71 + <reedit patch description [-e] if desired>
3.72 +
3.73 + # Now your changes are recorded, and `hg status` should show a clean
3.74 + # working copy
3.75 +
3.76 +Repeat the above steps for all your modifications.
3.77 +The command `hg qseries` informs you about the content of your patch queue.
3.78 +
3.79 +
3.80 +CONTRIBUTING YOUR PATCHES:
3.81 +
3.82 +Once you are satisfied with your patch series, you can (you should!)
3.83 +contribute them back to upstream.
3.84 +This is easily done using the `hg email` command.
3.85 +
3.86 +`hg email` sends your new changesets to a specified list of recipients,
3.87 +each patch in its own email, all ordered in the way you entered them (oldest
3.88 +first). The command line flag --outgoing selects all changesets that are in
3.89 +your local but not yet in the upstream repository. Here, these are exactly
3.90 +the ones you entered into your local patch queue in the section above, so
3.91 +--outgoing is what you want.
3.92 +
3.93 +Each email gets the subject set to: "[PATCH x of n] <series summary>"
3.94 +where 'x' is the serial number in the email series, and 'n' is the total number
3.95 +of patches in the series. The body of the email is the complete patch, plus
3.96 +a handful of metadata, that helps properly apply the patch, keeping the log
3.97 +message, attribution and date, tracking file changes (move, delete, modes...)
3.98 +
3.99 +`hg email` also threads all outgoing patch emails below an introductory
3.100 +message. You should use the introductory message (command line flag --intro)
3.101 +to describe the scope and motivation for the whole patch series. The subject
3.102 +for the introductory message gets set to: "[PATCH 0 of n] <series summary>"
3.103 +and you get the chance to set the <series summary>.
3.104 +
3.105 +Here is a sample `hg email` complete command line:
3.106 +Note: replace " (at) " with "@"
3.107 +
3.108 + hg email --outgoing --intro \
3.109 + --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>' \
3.110 + --cc 'crossgcc (at) sourceware.org'
3.111 +
3.112 + # It then opens an editor and lets you enter the subject
3.113 + # and the body for the introductory message.
3.114 +
3.115 +Use `hg email` with the additional command line switch -n to
3.116 +first have a look at the email(s) without actually sending them.
3.117 +
3.118 +
3.119 +MAINTAINING YOUR PATCHES:
3.120 +
3.121 +When the patches are refined by discussing them on the mailing list,
3.122 +you may want to finalize and resend them.
3.123 +
3.124 +The mq extension has the idiosyncrasy of imposing a stack onto the queue:
3.125 +You can always reedit/refresh only the patch on top of stack.
3.126 +The queue consists of applied and unapplied patches
3.127 +(if you reached here via the above steps, all of your patches are applied),
3.128 +where the 'stack' consists of the applied patches, and 'top of stack'
3.129 +is the latest applied patch.
3.130 +
3.131 +The following output of `hg qseries` is now used as an example:
3.132 + 0 A short_patch_name1
3.133 + 1 A short_patch_name2
3.134 + 2 A short_patch_name3
3.135 + 3 A short_patch_name4
3.136 +
3.137 +You are now able to edit patch 'short_patch_name4' (which is top of stack):
3.138 + <Edit the sources>
3.139 + # and execute again
3.140 + hg qrefresh -D [-e]
3.141 + <and optionally [-e] reedit the commit message>
3.142 +
3.143 +If you want to edit e.g. patch short_patch_name2, you have to modify
3.144 +mq's stack so this patch gets top of stack.
3.145 +For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
3.146 +
3.147 + hg qgoto short_patch_name2
3.148 + # The patch queue should now look like
3.149 + hg qseries
3.150 + 0 A short_patch_name1
3.151 + 1 A short_patch_name2
3.152 + 2 U short_patch_name3
3.153 + 3 U short_patch_name4
3.154 + # so patch # 1 (short_patch_name2) is top of stack.
3.155 + <now reedit the sources for short_patch_name2>
3.156 + # and execute again
3.157 + hg qrefresh -D [-e]
3.158 + <and optionally [-e] reedit the commit message>
3.159 + # the following command reapplies the now unapplied two patches:
3.160 + hg qpush -a
3.161 + # you can also use `hg qgoto short_patch_name4` to get there again.
3.162 +
3.163 +
3.164 +RESENDING YOUR REEDITED PATCHES:
3.165 +
3.166 +By mailing list policy, please resend your complete patch series.
3.167 +--> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
3.168 +
3.169 +
3.170 +SYNCING WITH UPSTREAM AGAIN:
3.171 +
3.172 +You can sync your repo with upstream at any time by executing
3.173 + # first unapply all your patches:
3.174 + hg qpop -a
3.175 + # next fetch new changesets from upstream
3.176 + hg pull
3.177 + # then update your working copy
3.178 + hg up
3.179 + # optionally remove already upstream integrated patches (see below)
3.180 + hg qdelete <short_name_of_already_applied_patch>
3.181 + # and reapply your patches if any non upstream-integrated left (but see below)
3.182 + hg qpush -a
3.183 +
3.184 +Eventually, your patches get included into the upstream repository
3.185 +which you initially cloned.
3.186 +In this case, before executing the hg qpush -a from above
3.187 +you should manually "hg qdelete" the patches that are already integrated upstream.
3.188 +
3.189 +
3.190 +HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
3.191 +
3.192 +Commit messages should look like (without leading pipes):
3.193 + |component: short, one-line description
3.194 + |
3.195 + |optional longer description
3.196 + |on multiple lines if needed
3.197 +
3.198 +Here is an example commit message (see revision a53a5e1d61db):
3.199 + |comp-libs/cloog: fix building
3.200 + |
3.201 + |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
3.202 + |For any later versions, the directory name does have the version, such as
3.203 + |cloog-ppl-0.15.4.