docs/C - Misc. tutorials.txt
author Titus von Boxberg <titus@v9g.de>
Mon Aug 22 09:41:35 2011 +0200 (2011-08-22)
branch1.12
changeset 2636 d53c6d529923
parent 2564 5d4e91c0343e
child 2626 c7c9e98d36d8
permissions -rw-r--r--
configure: fix --with-prog=[...]

check_for didn't set variable 'where' when the path to a prog
was passed manually "(cached)".

Signed-off-by: "Titus von Boxberg" <titus@v9g.de>
(transplanted from b1be254591e7b524a0b06a2247a9331ebe0faf1d)
     1 File.........: C - Misc. tutorials.txt
     2 Copyright....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
     3 License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
     4 
     5 
     6 Misc. tutorials  /
     7 ________________/
     8 
     9 
    10 Using crosstool-NG on FreeBSD (and other *BSD) |
    11 -----------------------------------------------+
    12 
    13 Contributed by: Titus von Boxberg
    14 
    15 Prerequisites and instructions for using ct-ng for building a cross toolchain on FreeBSD as host.
    16 
    17 0) Tested on FreeBSD 8.0
    18 
    19 1) Install (at least) the following ports
    20    archivers/lzma
    21    textproc/gsed
    22    devel/gmake
    23    devel/patch
    24    shells/bash
    25    devel/bison
    26    lang/gawk
    27    devel/automake110
    28    ftp/wget
    29 
    30    Of course, you should have /usr/local/bin in your PATH.
    31 
    32 2) run ct-ng's configure with the following tool configuration:
    33    ./configure --with-sed=/usr/local/bin/gsed --with-make=/usr/local/bin/gmake \
    34    --with-patch=/usr/local/bin/gpatch
    35    [...other configure parameters as you like...]
    36 
    37 3) proceed as described in general documentation
    38    but use gmake instead of make
    39 
    40 
    41 Using crosstool-NG on MacOS-X |
    42 ------------------------------+
    43 
    44 Contributed by: Titus von Boxberg
    45 
    46 Prerequisites and instructions for using crosstool-NG for building a cross
    47 toolchain on MacOS as host.
    48 
    49 0) Mac OS Snow Leopard, with Developer Tools 3.2 installed, or
    50    Mac OS Leopard, with Developer Tools & newer gcc (>= 4.3) installed
    51    via macports
    52 
    53 1) You have to use a case sensitive file system for ct-ng's build and target
    54    directories. Use a disk or disk image with a case sensitive fs that you
    55    mount somewhere.
    56 
    57 2) Install macports (or similar easy means of installing 3rd party software),
    58    make sure that macport's bin dir is in your PATH.
    59    Furtheron assuming it is /opt/local/bin.
    60 
    61 3) Install (at least) the following macports
    62    lzmautils
    63    libtool
    64    binutils
    65    gsed
    66    gawk
    67    gcc43 (only necessary for Leopard OSX 10.5)
    68 
    69    On Leopard, make sure that the macport's gcc is called with the default
    70    commands (gcc, g++,...), e.g. via macport gcc_select
    71 
    72 4) run ct-ng's configure with the following tool configuration
    73    (assuming you have installed the tools via macports in /opt/local):
    74    ./configure --with-sed=/opt/local/bin/gsed           \
    75                --with-libtool=/opt/local/bin/glibtool   \
    76                --with-objcopy=/opt/local/bin/gobjcopy   \
    77                --with-objdump=/opt/local/bin/gobjdump   \
    78                --with-readelf=/opt/local/bin/greadelf   \
    79                [...other configure parameters as you like...]
    80 
    81 5) proceed as described in standard documentation
    82 
    83 -----
    84 
    85 HINTS:
    86 - Apparently, GNU make's builtin variable .LIBPATTERNS is misconfigured
    87   under MacOS: It does not include lib%.dylib.
    88   This affects build of (at least) gdb-7.1
    89   Put 'lib%.a lib%.so lib%.dylib' as .LIBPATTERNS into your environment
    90   before executing ct-ng build.
    91   See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html
    92   as an explanation.
    93 - ct-ng menuconfig will not work on Snow Leopard 10.6.3 since libncurses
    94   is broken with this release. MacOS <= 10.6.2 and >= 10.6.4 are ok.
    95 
    96 
    97 Using Mercurial to hack crosstool-NG |
    98 -------------------------------------+
    99 
   100 Contributed by: Titus von Boxberg
   101 
   102 PREREQUISITES:
   103 
   104 Configuring Mercurial:
   105   You need mercurial with the following extensions:
   106    - mq        : http://mercurial.selenic.com/wiki/MqExtension
   107    - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
   108   Usually, these two extensions are already part of the installation package.
   109   The mq extension maintains a separate queue of your local changes
   110   that you can change at any later time.
   111   With the patchbomb extension you can email those patches directly
   112   from your local repo.
   113 
   114   Your configuration file for mercurial, e.g. ~/.hgrc should contain
   115   at least the following sections (but have a look at `man hgrc`):
   116   # ---
   117   [email]
   118   # configure sending patches directly via Mercurial
   119   from = "Your Name" <your@email.address>
   120   # How to send email:
   121   method = smtp
   122 
   123   [smtp]
   124   # SMTP configuration (only for method=smtp)
   125   host = localhost
   126   tls = true
   127   username =
   128   password =
   129 
   130   [extensions]
   131   # The following lines enable the two extensions:
   132   hgext.mq =
   133   hgext.patchbomb =
   134   # ----
   135 
   136 Create your local repository as a clone:
   137   hg clone http://crosstool-ng.org/hg/crosstool-ng crosstool-ng
   138 
   139 Setting up the mq extension in your local copy:
   140   cd crosstool-ng
   141   hg qinit
   142 
   143 
   144 CREATING PATCHES:
   145 
   146 Recording your changes in the patch queue maintained by mq:
   147   # First, create a new patch entry in the patch queue:
   148   hg qnew -D -U -e short_patch_name1
   149   <edit patch description as commit message (see below for an example)>
   150 
   151   <now edit the ct-ng sources and check them>
   152 
   153   # if you execute `hg status` here, your modifications of the working
   154   # copy should show up.
   155 
   156   # Now the following command takes your modifications from the working copy
   157   # into the patch entry
   158   hg qrefresh -D [-e]
   159   <reedit patch description [-e] if desired>
   160 
   161   # Now your changes are recorded, and `hg status` should show a clean
   162   # working copy
   163 
   164 Repeat the above steps for all your modifications.
   165 The command `hg qseries` informs you about the content of your patch queue.
   166 
   167 
   168 CONTRIBUTING YOUR PATCHES:
   169 
   170 Once you are satisfied with your patch series, you can (you should!)
   171 contribute them back to upstream.
   172 This is easily done using the `hg email` command.
   173 
   174 `hg email` sends your new changesets to a specified list of recipients,
   175 each patch in its own email, all ordered in the way you entered them (oldest
   176 first). The command line flag --outgoing selects all changesets that are in
   177 your local but not yet in the upstream repository. Here, these are exactly
   178 the ones you entered into your local patch queue in the section above, so
   179 --outgoing is what you want.
   180 
   181 Each email gets the subject set to:  "[PATCH x of n] <series summary>"
   182 where 'x' is the serial number in the email series, and 'n' is the total number
   183 of patches in the series. The body of the email is the complete patch, plus
   184 a handful of metadata, that helps properly apply the patch, keeping the log
   185 message, attribution and date, tracking file changes (move, delete, modes...)
   186 
   187 `hg email` also threads all outgoing patch emails below an introductory
   188 message. You should use the introductory message (command line flag --intro)
   189 to describe the scope and motivation for the whole patch series. The subject
   190 for the introductory message gets set to:  "[PATCH 0 of n] <series summary>"
   191 and you get the chance to set the <series summary>.
   192 
   193 Here is a sample `hg email` complete command line:
   194 Note: replace " (at) " with "@"
   195 
   196   hg email --outgoing --intro   \
   197            --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>'    \
   198            --cc 'crossgcc (at) sourceware.org'
   199 
   200   # It then opens an editor and lets you enter the subject
   201   # and the body for the introductory message.
   202 
   203 Use `hg email` with the additional command line switch -n to
   204 first have a look at the email(s) without actually sending them.
   205 
   206 
   207 MAINTAINING YOUR PATCHES:
   208 
   209 When the patches are refined by discussing them on the mailing list,
   210 you may want to finalize and resend them.
   211 
   212 The mq extension has the idiosyncrasy of imposing a stack onto the queue:
   213 You can always reedit/refresh only the patch on top of stack.
   214 The queue consists of applied and unapplied patches
   215 (if you reached here via the above steps, all of your patches are applied),
   216 where the 'stack' consists of the applied patches, and 'top of stack'
   217 is the latest applied patch.
   218 
   219 The following output of `hg qseries` is now used as an example:
   220   0 A short_patch_name1
   221   1 A short_patch_name2
   222   2 A short_patch_name3
   223   3 A short_patch_name4
   224 
   225 You are now able to edit patch 'short_patch_name4' (which is top of stack):
   226   <Edit the sources>
   227   # and execute again
   228   hg qrefresh -D [-e]
   229   <and optionally [-e] reedit the commit message>
   230 
   231 If you want to edit e.g. patch short_patch_name2, you have to modify
   232 mq's stack so this patch gets top of stack.
   233 For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
   234 
   235   hg qgoto short_patch_name2
   236   # The patch queue should now look like
   237   hg qseries
   238     0 A short_patch_name1
   239     1 A short_patch_name2
   240     2 U short_patch_name3
   241     3 U short_patch_name4
   242   # so patch # 1 (short_patch_name2) is top of stack.
   243   <now reedit the sources for short_patch_name2>
   244   # and execute again
   245   hg qrefresh -D [-e]
   246   <and optionally [-e] reedit the commit message>
   247   # the following command reapplies the now unapplied two patches:
   248   hg qpush -a
   249   # you can also use `hg qgoto short_patch_name4` to get there again.
   250 
   251 
   252 RESENDING YOUR REEDITED PATCHES:
   253 
   254 By mailing list policy, please resend your complete patch series.
   255 --> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
   256 
   257 
   258 SYNCING WITH UPSTREAM AGAIN:
   259 
   260 You can sync your repo with upstream at any time by executing
   261   # first unapply all your patches:
   262   hg qpop -a
   263   # next fetch new changesets from upstream
   264   hg pull
   265   # then update your working copy
   266   hg up
   267   # optionally remove already upstream integrated patches (see below)
   268   hg qdelete <short_name_of_already_applied_patch>
   269   # and reapply your patches if any non upstream-integrated left (but see below)
   270   hg qpush -a
   271 
   272 Eventually, your patches get included into the upstream repository
   273 which you initially cloned.
   274 In this case, before executing the hg qpush -a from above
   275 you should manually "hg qdelete" the patches that are already integrated upstream.
   276 
   277 
   278 HOW TO FORMAT COMMIT MESSAGES (aka patch descriptions):
   279 
   280 Commit messages should look like (without leading pipes):
   281  |component: short, one-line description
   282  |
   283  |optional longer description
   284  |on multiple lines if needed
   285  |
   286  |Signed-off-by: as documented in section 7 of ct-ng's documentation
   287 
   288 Here is an example commit message (see revision 8bb5151c5b01):
   289  kernel/linux: fix type in version strings
   290 
   291  I missed refreshing the patch before pushing. :-(
   292 
   293  Signed-off-by: "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>