docs/C - Misc. tutorials.txt
author "Yann E. MORIN" <yann.morin.1998@free.fr>
Sun May 11 17:51:33 2014 +0200 (2014-05-11)
changeset 3317 6b2c4692f132
parent 2628 a4f56e266879
permissions -rw-r--r--
binutils/elf2flt: restore the custom location functionality

Somehow, it got lost when incorporating elf2flt in the binutils farmework.

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