docs/C - Misc. tutorials.txt
author "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Thu Aug 26 23:36:54 2010 +0200 (2010-08-26)
changeset 2096 5f01a23be1e4
parent 2076 b58109b7b321
child 2530 5a4d97b2d272
permissions -rw-r--r--
scripts/log: do not interpret log string as printf format

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
     1 File.........: C - Misc. tutorials.txt
     2 Copyrigth....: (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    ncurses
    63    lzmautils
    64    libtool
    65    binutils
    66    gsed
    67    gawk
    68    gcc43 (only necessary for Leopard OSX 10.5)
    69 
    70    On Leopard, make sure that the macport's gcc is called with the default
    71    commands (gcc, g++,...), e.g. via macport gcc_select
    72 
    73 4) run ct-ng's configure with the following tool configuration
    74    (assuming you have installed the tools via macports in /opt/local):
    75    ./configure --with-sed=/opt/local/bin/gsed           \
    76                --with-libtool=/opt/local/bin/glibtool   \
    77                --with-objcopy=/opt/local/bin/gobjcopy   \
    78                --with-objdump=/opt/local/bin/gobjdump   \
    79                --with-readelf=/opt/local/bin/greadelf   \
    80                [...other configure parameters as you like...]
    81 
    82 5) proceed as described in standard documentation
    83 
    84 -----
    85 
    86 HINTS:
    87 - Apparently, GNU make's builtin variable .LIBPATTERNS is misconfigured
    88   under MacOS: It does not include lib%.dylib.
    89   This affects build of (at least) gdb-7.1
    90   Put 'lib%.a lib%.so lib%.dylib' as .LIBPATTERNS into your environment
    91   before executing ct-ng build.
    92   See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html
    93   as an explanation.
    94 
    95 
    96 Using Mercurial to hack crosstool-NG |
    97 -------------------------------------+
    98 
    99 Contributed by: Titus von Boxberg
   100 
   101 PREREQUISITES:
   102 
   103 Configuring Mercurial:
   104   You need mercurial with the following extensions:
   105    - mq        : http://mercurial.selenic.com/wiki/MqExtension
   106    - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
   107   Usually, these two extensions are already part of the installation package.
   108   The mq extension maintains a separate queue of your local changes
   109   that you can change at any later time.
   110   With the patchbomb extension you can email those patches directly
   111   from your local repo.
   112 
   113   Your configuration file for mercurial, e.g. ~/.hgrc should contain
   114   at least the following sections (but have a look at `man hgrc`):
   115   # ---
   116   [email]
   117   # configure sending patches directly via Mercurial
   118   from = "Your Name" <your@email.address>
   119   # How to send email:
   120   method = smtp
   121 
   122   [smtp]
   123   # SMTP configuration (only for method=smtp)
   124   host = localhost
   125   tls = true
   126   username =
   127   password =
   128 
   129   [extensions]
   130   # The following lines enable the two extensions:
   131   hgext.mq =
   132   hgext.patchbomb =
   133   # ----
   134 
   135 Create your local repository as a clone:
   136   hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
   137 
   138 Setting up the mq extension in your local copy:
   139   cd crosstool-ng
   140   hg qinit
   141 
   142 
   143 CREATING PATCHES:
   144 
   145 Recording your changes in the patch queue maintained by mq:
   146   # First, create a new patch entry in the patch queue:
   147   hg qnew -D -U -e short_patch_name1
   148   <edit patch description as commit message (see below for an example)>
   149 
   150   <now edit the ct-ng sources and check them>
   151 
   152   # if you execute `hg status` here, your modifications of the working
   153   # copy should show up.
   154 
   155   # Now the following command takes your modifications from the working copy
   156   # into the patch entry
   157   hg qrefresh -D [-e]
   158   <reedit patch description [-e] if desired>
   159 
   160   # Now your changes are recorded, and `hg status` should show a clean
   161   # working copy
   162 
   163 Repeat the above steps for all your modifications.
   164 The command `hg qseries` informs you about the content of your patch queue.
   165 
   166 
   167 CONTRIBUTING YOUR PATCHES:
   168 
   169 Once you are satisfied with your patch series, you can (you should!)
   170 contribute them back to upstream.
   171 This is easily done using the `hg email` command.
   172 
   173 `hg email` sends your new changesets to a specified list of recipients,
   174 each patch in its own email, all ordered in the way you entered them (oldest
   175 first). The command line flag --outgoing selects all changesets that are in
   176 your local but not yet in the upstream repository. Here, these are exactly
   177 the ones you entered into your local patch queue in the section above, so
   178 --outgoing is what you want.
   179 
   180 Each email gets the subject set to:  "[PATCH x of n] <series summary>"
   181 where 'x' is the serial number in the email series, and 'n' is the total number
   182 of patches in the series. The body of the email is the complete patch, plus
   183 a handful of metadata, that helps properly apply the patch, keeping the log
   184 message, attribution and date, tracking file changes (move, delete, modes...)
   185 
   186 `hg email` also threads all outgoing patch emails below an introductory
   187 message. You should use the introductory message (command line flag --intro)
   188 to describe the scope and motivation for the whole patch series. The subject
   189 for the introductory message gets set to:  "[PATCH 0 of n] <series summary>"
   190 and you get the chance to set the <series summary>.
   191 
   192 Here is a sample `hg email` complete command line:
   193 Note: replace " (at) " with "@"
   194 
   195   hg email --outgoing --intro   \
   196            --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>'    \
   197            --cc 'crossgcc (at) sourceware.org'
   198 
   199   # It then opens an editor and lets you enter the subject
   200   # and the body for the introductory message.
   201 
   202 Use `hg email` with the additional command line switch -n to
   203 first have a look at the email(s) without actually sending them.
   204 
   205 
   206 MAINTAINING YOUR PATCHES:
   207 
   208 When the patches are refined by discussing them on the mailing list,
   209 you may want to finalize and resend them.
   210 
   211 The mq extension has the idiosyncrasy of imposing a stack onto the queue:
   212 You can always reedit/refresh only the patch on top of stack.
   213 The queue consists of applied and unapplied patches
   214 (if you reached here via the above steps, all of your patches are applied),
   215 where the 'stack' consists of the applied patches, and 'top of stack'
   216 is the latest applied patch.
   217 
   218 The following output of `hg qseries` is now used as an example:
   219   0 A short_patch_name1
   220   1 A short_patch_name2
   221   2 A short_patch_name3
   222   3 A short_patch_name4
   223 
   224 You are now able to edit patch 'short_patch_name4' (which is top of stack):
   225   <Edit the sources>
   226   # and execute again
   227   hg qrefresh -D [-e]
   228   <and optionally [-e] reedit the commit message>
   229 
   230 If you want to edit e.g. patch short_patch_name2, you have to modify
   231 mq's stack so this patch gets top of stack.
   232 For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
   233 
   234   hg qgoto short_patch_name2
   235   # The patch queue should now look like
   236   hg qseries
   237     0 A short_patch_name1
   238     1 A short_patch_name2
   239     2 U short_patch_name3
   240     3 U short_patch_name4
   241   # so patch # 1 (short_patch_name2) is top of stack.
   242   <now reedit the sources for short_patch_name2>
   243   # and execute again
   244   hg qrefresh -D [-e]
   245   <and optionally [-e] reedit the commit message>
   246   # the following command reapplies the now unapplied two patches:
   247   hg qpush -a
   248   # you can also use `hg qgoto short_patch_name4` to get there again.
   249 
   250 
   251 RESENDING YOUR REEDITED PATCHES:
   252 
   253 By mailing list policy, please resend your complete patch series.
   254 --> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
   255 
   256 
   257 SYNCING WITH UPSTREAM AGAIN:
   258 
   259 You can sync your repo with upstream at any time by executing
   260   # first unapply all your patches:
   261   hg qpop -a
   262   # next fetch new changesets from upstream
   263   hg pull
   264   # then update your working copy
   265   hg up
   266   # optionally remove already upstream integrated patches (see below)
   267   hg qdelete <short_name_of_already_applied_patch>
   268   # and reapply your patches if any non upstream-integrated left (but see below)
   269   hg qpush -a
   270 
   271 Eventually, your patches get included into the upstream repository
   272 which you initially cloned.
   273 In this case, before executing the hg qpush -a from above
   274 you should manually "hg qdelete" the patches that are already integrated upstream.
   275 
   276 
   277 HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
   278 
   279 Commit messages should look like (without leading pipes):
   280  |component: short, one-line description
   281  |
   282  |optional longer description
   283  |on multiple lines if needed
   284 
   285 Here is an example commit message (see revision a53a5e1d61db):
   286  |comp-libs/cloog: fix building
   287  |
   288  |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
   289  |For any later versions, the directory name does have the version, such as
   290  |cloog-ppl-0.15.4.