summaryrefslogtreecommitdiff
path: root/docs/C - Misc. tutorials.txt
blob: 0735c9e0dbc2f41a4d3d4925a8353b253656a862 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
File.........: C - Misc. tutorials.txt
Copyright....: (C) 2010 Yann E. MORIN <yann.morin.1998@free.fr>
License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5


Misc. tutorials  /
________________/


Using crosstool-NG on FreeBSD (and other *BSD) |
-----------------------------------------------+

Contributed by: Titus von Boxberg

Prerequisites and instructions for using ct-ng for building a cross toolchain on FreeBSD as host.

0) Tested on FreeBSD 8.0

1) Install (at least) the following ports
   archivers/lzma
   textproc/gsed
   devel/gmake
   devel/patch
   shells/bash
   devel/bison
   lang/gawk
   devel/automake110
   ftp/wget

   Of course, you should have /usr/local/bin in your PATH.

2) run ct-ng's configure with the following tool configuration:
   ./configure --with-sed=/usr/local/bin/gsed --with-make=/usr/local/bin/gmake \
   --with-patch=/usr/local/bin/gpatch
   [...other configure parameters as you like...]

3) proceed as described in general documentation
   but use gmake instead of make


Using crosstool-NG on MacOS-X |
------------------------------+

Contributed by: Titus von Boxberg

Prerequisites and instructions for using crosstool-NG for building a cross
toolchain on MacOS as host.

0) Mac OS Snow Leopard, with Developer Tools 3.2 installed, or
   Mac OS Leopard, with Developer Tools & newer gcc (>= 4.3) installed
   via macports

1) You have to use a case sensitive file system for ct-ng's build and target
   directories. Use a disk or disk image with a case sensitive fs that you
   mount somewhere.

2) Install macports (or similar easy means of installing 3rd party software),
   make sure that macport's bin dir is in the front (!) of your PATH.
   Furtheron assuming it is /opt/local/bin.

3) Install (at least) the following macports
   lzmautils
   libtool
   binutils
   gsed
   gawk
   gcc43 (only necessary for Leopard OSX 10.5)
   gcc_select (only necessary for OSX 10.5, or Xcode > 4)

4) Prerequisites
   On Leopard, make sure that the macport's gcc is called with the default
   commands (gcc, g++,...), via macport's gcc_select

   On OSX 10.7 Lion / when using Xcode >= 4 make sure that the default commands
   (gcc, g++, etc.) point to gcc-4.2, NOT llvm-gcc-4.2
   by using macport's gcc_select feature. With MacPorts >= 1.9.2
   the command is: "sudo port select --set gcc gcc42"
   This also requires (like written above) that macport's bin dir
   comes before standard directories in your PATH environment variable
   because the gcc symlink is installed in /opt/local/bin and the default /usr/bin/gcc
   is not removed by the gcc select command!
   Explanation: llvm-gcc-4.2 (with Xcode 4.1 it is on my machine
   "gcc version 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.00)")
   cannot boostrap gcc. See http://llvm.org/bugs/show_bug.cgi?id=9571

5) run ct-ng's configure with the following tool configuration
   (assuming you have installed the tools via macports in /opt/local):
   ./configure --with-sed=/opt/local/bin/gsed                 \
               --with-libtool=/opt/local/bin/glibtool         \
               --with-libtoolize=/opt/local/bin/glibtoolize   \
               --with-objcopy=/opt/local/bin/gobjcopy         \
               --with-objdump=/opt/local/bin/gobjdump         \
               --with-readelf=/opt/local/bin/greadelf         \
               --with-grep=/opt/local/bin/ggrep               \
               [...other configure parameters as you like...]

6) proceed as described in standard documentation

-----

HINTS:
- Apparently, GNU make's builtin variable .LIBPATTERNS is misconfigured
  under MacOS: It does not include lib%.dylib.
  This affects build of (at least) gdb-7.1
  Put 'lib%.a lib%.so lib%.dylib' as .LIBPATTERNS into your environment
  before executing ct-ng build.
  See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html
  as an explanation.
- ct-ng menuconfig will not work on Snow Leopard 10.6.3 since libncurses
  is broken with this release. MacOS <= 10.6.2 and >= 10.6.4 are ok.


Using Mercurial to hack crosstool-NG |
-------------------------------------+

NOTE: this section was applicable as long as when we were using Mercurial (Hg)
as the DVCS. Now we've switched to git, this section is no longer current. We
keep it as a reference, since it still contains a few useful hints.

Please help rewrite this section. ;-)

Contributed by: Titus von Boxberg

PREREQUISITES:

Configuring Mercurial:
  You need mercurial with the following extensions:
   - mq        : http://mercurial.selenic.com/wiki/MqExtension
   - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
  Usually, these two extensions are already part of the installation package.
  The mq extension maintains a separate queue of your local changes
  that you can change at any later time.
  With the patchbomb extension you can email those patches directly
  from your local repo.

  Your configuration file for mercurial, e.g. ~/.hgrc should contain
  at least the following sections (but have a look at `man hgrc`):
  # ---
  [email]
  # configure sending patches directly via Mercurial
  from = "Your Name" <your@email.address>
  # How to send email:
  method = smtp

  [smtp]
  # SMTP configuration (only for method=smtp)
  host = localhost
  tls = true
  username =
  password =

  [extensions]
  # The following lines enable the two extensions:
  hgext.mq =
  hgext.patchbomb =
  # ----

Create your local repository as a clone:
  hg clone http://crosstool-ng.org/hg/crosstool-ng crosstool-ng

Setting up the mq extension in your local copy:
  cd crosstool-ng
  hg qinit


CREATING PATCHES:

Recording your changes in the patch queue maintained by mq:
  # First, create a new patch entry in the patch queue:
  hg qnew -D -U -e short_patch_name1
  <edit patch description as commit message (see below for an example)>

  <now edit the ct-ng sources and check them>

  # if you execute `hg status` here, your modifications of the working
  # copy should show up.

  # Now the following command takes your modifications from the working copy
  # into the patch entry
  hg qrefresh -D [-e]
  <reedit patch description [-e] if desired>

  # Now your changes are recorded, and `hg status` should show a clean
  # working copy

Repeat the above steps for all your modifications.
The command `hg qseries` informs you about the content of your patch queue.


CONTRIBUTING YOUR PATCHES:

Once you are satisfied with your patch series, you can (you should!)
contribute them back to upstream.
This is easily done using the `hg email` command.

`hg email` sends your new changesets to a specified list of recipients,
each patch in its own email, all ordered in the way you entered them (oldest
first). The command line flag --outgoing selects all changesets that are in
your local but not yet in the upstream repository. Here, these are exactly
the ones you entered into your local patch queue in the section above, so
--outgoing is what you want.

Each email gets the subject set to:  "[PATCH x of n] <series summary>"
where 'x' is the serial number in the email series, and 'n' is the total number
of patches in the series. The body of the email is the complete patch, plus
a handful of metadata, that helps properly apply the patch, keeping the log
message, attribution and date, tracking file changes (move, delete, modes...)

`hg email` also threads all outgoing patch emails below an introductory
message. You should use the introductory message (command line flag --intro)
to describe the scope and motivation for the whole patch series. The subject
for the introductory message gets set to:  "[PATCH 0 of n] <series summary>"
and you get the chance to set the <series summary>.

Here is a sample `hg email` complete command line:
Note: replace " (at) " with "@"

  hg email --outgoing --intro   \
           --to '"Yann E. MORIN" <yann.morin.1998 (at) free.fr>'    \
           --cc 'crossgcc (at) sourceware.org'

  # It then opens an editor and lets you enter the subject
  # and the body for the introductory message.

Use `hg email` with the additional command line switch -n to
first have a look at the email(s) without actually sending them.


MAINTAINING YOUR PATCHES:

When the patches are refined by discussing them on the mailing list,
you may want to finalize and resend them.

The mq extension has the idiosyncrasy of imposing a stack onto the queue:
You can always reedit/refresh only the patch on top of stack.
The queue consists of applied and unapplied patches
(if you reached here via the above steps, all of your patches are applied),
where the 'stack' consists of the applied patches, and 'top of stack'
is the latest applied patch.

The following output of `hg qseries` is now used as an example:
  0 A short_patch_name1
  1 A short_patch_name2
  2 A short_patch_name3
  3 A short_patch_name4

You are now able to edit patch 'short_patch_name4' (which is top of stack):
  <Edit the sources>
  # and execute again
  hg qrefresh -D [-e]
  <and optionally [-e] reedit the commit message>

If you want to edit e.g. patch short_patch_name2, you have to modify
mq's stack so this patch gets top of stack.
For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.

  hg qgoto short_patch_name2
  # The patch queue should now look like
  hg qseries
    0 A short_patch_name1
    1 A short_patch_name2
    2 U short_patch_name3
    3 U short_patch_name4
  # so patch # 1 (short_patch_name2) is top of stack.
  <now reedit the sources for short_patch_name2>
  # and execute again
  hg qrefresh -D [-e]
  <and optionally [-e] reedit the commit message>
  # the following command reapplies the now unapplied two patches:
  hg qpush -a
  # you can also use `hg qgoto short_patch_name4` to get there again.


RESENDING YOUR REEDITED PATCHES:

By mailing list policy, please resend your complete patch series.
--> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.


SYNCING WITH UPSTREAM AGAIN:

You can sync your repo with upstream at any time by executing
  # first unapply all your patches:
  hg qpop -a
  # next fetch new changesets from upstream
  hg pull
  # then update your working copy
  hg up
  # optionally remove already upstream integrated patches (see below)
  hg qdelete <short_name_of_already_applied_patch>
  # and reapply your patches if any non upstream-integrated left (but see below)
  hg qpush -a

Eventually, your patches get included into the upstream repository
which you initially cloned.
In this case, before executing the hg qpush -a from above
you should manually "hg qdelete" the patches that are already integrated upstream.


HOW TO FORMAT COMMIT MESSAGES (aka patch descriptions):

Commit messages should look like (without leading pipes):
 |component: short, one-line description
 |
 |optional longer description
 |on multiple lines if needed
 |
 |Signed-off-by: as documented in section 7 of ct-ng's documentation

Here is an example commit message (see revision 8bb5151c5b01):
 kernel/linux: fix type in version strings

 I missed refreshing the patch before pushing. :-(

 Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

Using crosstool-NG on Windows |
------------------------------+

Contributed by: Ray Donnelly

Prerequisites and instructions for using crosstool-NG for building a cross
toolchain on Windows (Cygwin) as build and, optionally Windows (hereafter)
MinGW-w64 as host.

0. Use Cygwin64 if you can. DLL base-address problems are lessened that
   way and if you bought a 64-bit CPU, you may as well use it.

1. You must enable Case Sensitivity in the Windows Kernel (this is only really
   necessary for Linux targets, but at present, crosstool-ng refuses to operate
   on case insensitive filesystems). The registry key for this is:
   HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive
   Read more at:
   https://cygwin.com/cygwin-ug-net/using-specialnames.html

2. Using setup{,-x86_64}.exe, install the default packages and also the
   following ones: (tested versions in brackets, please test newer versions
   and report successes via pull requests changing this list and failures to:
   https://github.com/crosstool-ng/crosstool-ng/issues
   autoconf (13-1), make (4.1-1), gcc-g++ (4.9.3-1), gperf (3.0.4-2),
   bison (3.0.4-1), flex (2.5.39-1), texinfo (6.0-1), wget (1.16.3-1),
   patch (2.7.4-1), libtool (2.4.6-2), automake (9-1), diffutils (3.3-3),
   libncurses-devel (6.0-1.20151017), help2man (1.44.1-1)
   mingw64-i686-gcc-g++* (4.9.2-2), mingw64-x86_64-gcc-g++* (4.9.2-2)
   Leave "Select required packages (RECOMMENDED)" ticked.
   Notes:
   2.1 The packages marked with * are only needed if your host is MinGW-w64.
   2.2 Unfortunately, wget pulls in an awful lot of dependencies, including
       Python 2.7, Ruby, glib and Tcl.

3. Although nativestrict symlinks seem like the best idea, extracting glibc fails
   when they are enabled, so just don't set anything here. If your host is MinGW-w64
   then these 'Cygwin-special' symlinks won't work, but you can dereference them by
   using tar options --dereference and --hard-dereference when making a final tarball.
   I plan to investigate and fix or at least work around the extraction problem.
   Read more at:
   https://cygwin.com/cygwin-ug-net/using-cygwinenv.html

4. collect2.exe will attempt to run ld which is a shell script that runs either
   ld.exe or gold.exe so you need to make sure that a working shell is in your path.
   Eventually I will replace this with a native program for MinGW-w64 host.

Using crosstool-NG to build Xtensa toolchains |
----------------------------------------------+

Contributed by: Max Filippov

Xtensa cores are highly configurable: endianness, instruction set, register set
of a core is chosen at processor configuration time. New registers and
instructions may be added by designers, making each core configuration unique.
Toolchain components cannot know about features of each individual core and
need to be configured in order to be compatible with particular architecture
variant. This configuration includes:
- definitions of instruction formats, names and properties for assembler,
  disassembler and debugger;
- definitions of register names and properties for assembler, disassembler and
  debugger;
- selection of predefined features, such as endianness, presence of certain
  processor options or instructions for compiler, debugger C library and OS
  kernels;
- macros with instruction sequences for saving and restoring special, user or
  coprocessor registers for OS kernels.

This configuration is provided in form of source files, that must replace
corresponding files in binutils, gcc, gdb or newlib source trees or be added
to OS kernel source tree. This set of files is usually distributed as archive
known as Xtensa configuration overlay.

Tensilica provides such an overlay as part of the processor download, however,
it needs to be reformatted to match the specific format required by the
crosstool-NG. For a script to convert the overlay file, and additional
information, please see
  http://wiki.linux-xtensa.org/index.php/Toolchain_Overlay_File

The current version of crosstool-NG requires that the overlay file name has the
format xtensa_<CORE_NAME>.tar, where CORE_NAME can be any user selected name.
To make crosstool-NG use overlay file located at <PATH>/xtensa_<CORE_NAME>.tar
select XTENSA_CUSTOM, set config parameter CT_ARCH_XTENSA_CUSTOM_NAME to
CORE_NAME and CT_ARCH_XTENSA_CUSTOM_OVERLAY_LOCATION to PATH.

The fsf target architecture variant is the configuration provided by toolchain
components by default. It is present only for build-testing toolchain
components and is in no way special or universal.