docs/C - Misc. tutorials.txt
author "Yann E. MORIN" <yann.morin.1998@free.fr>
Mon May 26 23:25:17 2014 +0200 (2014-05-26)
changeset 3324 1eea25c0bfe7
parent 2628 a4f56e266879
permissions -rw-r--r--
complibs/cloog: remove old CLooG/PPL versions

Those versions are no longer available upstream. They have purely and
simply disapeared, without leaving any trace of their mere existences.

Just keep the latest cloog-ppl-0.15.11, which still exists on the gcc
infra mirror (but for how long?)

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