yann@2076: File.........: C - Misc. tutorials.txt yann@2908: Copyright....: (C) 2010 Yann E. MORIN yann@2076: License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5 yann@2076: yann@2076: yann@2076: Misc. tutorials / yann@2076: ________________/ yann@2076: yann@2076: yann@2076: Using crosstool-NG on FreeBSD (and other *BSD) | yann@2076: -----------------------------------------------+ yann@2076: yann@2076: Contributed by: Titus von Boxberg yann@2076: yann@2076: Prerequisites and instructions for using ct-ng for building a cross toolchain on FreeBSD as host. yann@2076: yann@2076: 0) Tested on FreeBSD 8.0 yann@2076: yann@2076: 1) Install (at least) the following ports yann@2076: archivers/lzma yann@2076: textproc/gsed yann@2076: devel/gmake yann@2076: devel/patch yann@2076: shells/bash yann@2076: devel/bison yann@2076: lang/gawk yann@2076: devel/automake110 yann@2076: ftp/wget yann@2076: yann@2076: Of course, you should have /usr/local/bin in your PATH. yann@2076: yann@2076: 2) run ct-ng's configure with the following tool configuration: yann@2076: ./configure --with-sed=/usr/local/bin/gsed --with-make=/usr/local/bin/gmake \ yann@2076: --with-patch=/usr/local/bin/gpatch yann@2076: [...other configure parameters as you like...] yann@2076: yann@2076: 3) proceed as described in general documentation yann@2076: but use gmake instead of make yann@2076: yann@2076: yann@2076: Using crosstool-NG on MacOS-X | yann@2076: ------------------------------+ yann@2076: yann@2076: Contributed by: Titus von Boxberg yann@2076: yann@2076: Prerequisites and instructions for using crosstool-NG for building a cross yann@2076: toolchain on MacOS as host. yann@2076: yann@2076: 0) Mac OS Snow Leopard, with Developer Tools 3.2 installed, or yann@2076: Mac OS Leopard, with Developer Tools & newer gcc (>= 4.3) installed yann@2076: via macports yann@2076: yann@2076: 1) You have to use a case sensitive file system for ct-ng's build and target yann@2076: directories. Use a disk or disk image with a case sensitive fs that you yann@2076: mount somewhere. yann@2076: yann@2076: 2) Install macports (or similar easy means of installing 3rd party software), titus@2628: make sure that macport's bin dir is in the front (!) of your PATH. yann@2076: Furtheron assuming it is /opt/local/bin. yann@2076: yann@2076: 3) Install (at least) the following macports yann@2076: lzmautils yann@2076: libtool yann@2076: binutils yann@2076: gsed yann@2076: gawk yann@2076: gcc43 (only necessary for Leopard OSX 10.5) titus@2628: gcc_select (only necessary for OSX 10.5, or Xcode > 4) yann@2076: titus@2628: 4) Prerequisites yann@2076: On Leopard, make sure that the macport's gcc is called with the default titus@2628: commands (gcc, g++,...), via macport's gcc_select yann@2076: titus@2628: On OSX 10.7 Lion / when using Xcode >= 4 make sure that the default commands titus@2628: (gcc, g++, etc.) point to gcc-4.2, NOT llvm-gcc-4.2 titus@2628: by using macport's gcc_select feature. With MacPorts >= 1.9.2 titus@2628: the command is: "sudo port select --set gcc gcc42" titus@2628: This also requires (like written above) that macport's bin dir titus@2628: comes before standard directories in your PATH environment variable titus@2628: because the gcc symlink is installed in /opt/local/bin and the default /usr/bin/gcc titus@2628: is not removed by the gcc select command! titus@2628: Explanation: llvm-gcc-4.2 (with Xcode 4.1 it is on my machine titus@2628: "gcc version 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.00)") titus@2628: cannot boostrap gcc. See http://llvm.org/bugs/show_bug.cgi?id=9571 titus@2628: titus@2628: 5) run ct-ng's configure with the following tool configuration yann@2076: (assuming you have installed the tools via macports in /opt/local): titus@2626: ./configure --with-sed=/opt/local/bin/gsed \ titus@2626: --with-libtool=/opt/local/bin/glibtool \ titus@2626: --with-libtoolize=/opt/local/bin/glibtoolize \ titus@2626: --with-objcopy=/opt/local/bin/gobjcopy \ titus@2626: --with-objdump=/opt/local/bin/gobjdump \ titus@2626: --with-readelf=/opt/local/bin/greadelf \ yann@2076: [...other configure parameters as you like...] yann@2076: titus@2628: 6) proceed as described in standard documentation yann@2076: yann@2076: ----- yann@2076: yann@2076: HINTS: yann@2076: - Apparently, GNU make's builtin variable .LIBPATTERNS is misconfigured yann@2076: under MacOS: It does not include lib%.dylib. yann@2076: This affects build of (at least) gdb-7.1 yann@2076: Put 'lib%.a lib%.so lib%.dylib' as .LIBPATTERNS into your environment yann@2076: before executing ct-ng build. yann@2076: See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html yann@2076: as an explanation. titus@2531: - ct-ng menuconfig will not work on Snow Leopard 10.6.3 since libncurses titus@2531: is broken with this release. MacOS <= 10.6.2 and >= 10.6.4 are ok. yann@2077: yann@2077: yann@2077: Using Mercurial to hack crosstool-NG | yann@2077: -------------------------------------+ yann@2077: yann@2077: Contributed by: Titus von Boxberg yann@2077: yann@2077: PREREQUISITES: yann@2077: yann@2077: Configuring Mercurial: yann@2077: You need mercurial with the following extensions: yann@2077: - mq : http://mercurial.selenic.com/wiki/MqExtension yann@2077: - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension yann@2077: Usually, these two extensions are already part of the installation package. yann@2077: The mq extension maintains a separate queue of your local changes yann@2077: that you can change at any later time. yann@2077: With the patchbomb extension you can email those patches directly yann@2077: from your local repo. yann@2077: yann@2077: Your configuration file for mercurial, e.g. ~/.hgrc should contain yann@2077: at least the following sections (but have a look at `man hgrc`): yann@2077: # --- yann@2077: [email] yann@2077: # configure sending patches directly via Mercurial yann@2077: from = "Your Name" yann@2077: # How to send email: yann@2077: method = smtp yann@2077: yann@2077: [smtp] yann@2077: # SMTP configuration (only for method=smtp) yann@2077: host = localhost yann@2077: tls = true yann@2077: username = yann@2077: password = yann@2077: yann@2077: [extensions] yann@2077: # The following lines enable the two extensions: yann@2077: hgext.mq = yann@2077: hgext.patchbomb = yann@2077: # ---- yann@2077: yann@2077: Create your local repository as a clone: titus@2530: hg clone http://crosstool-ng.org/hg/crosstool-ng crosstool-ng yann@2077: yann@2077: Setting up the mq extension in your local copy: yann@2077: cd crosstool-ng yann@2077: hg qinit yann@2077: yann@2077: yann@2077: CREATING PATCHES: yann@2077: yann@2077: Recording your changes in the patch queue maintained by mq: yann@2077: # First, create a new patch entry in the patch queue: yann@2077: hg qnew -D -U -e short_patch_name1 yann@2077: yann@2077: yann@2077: yann@2077: yann@2077: # if you execute `hg status` here, your modifications of the working yann@2077: # copy should show up. yann@2077: yann@2077: # Now the following command takes your modifications from the working copy yann@2077: # into the patch entry yann@2077: hg qrefresh -D [-e] yann@2077: yann@2077: yann@2077: # Now your changes are recorded, and `hg status` should show a clean yann@2077: # working copy yann@2077: yann@2077: Repeat the above steps for all your modifications. yann@2077: The command `hg qseries` informs you about the content of your patch queue. yann@2077: yann@2077: yann@2077: CONTRIBUTING YOUR PATCHES: yann@2077: yann@2077: Once you are satisfied with your patch series, you can (you should!) yann@2077: contribute them back to upstream. yann@2077: This is easily done using the `hg email` command. yann@2077: yann@2077: `hg email` sends your new changesets to a specified list of recipients, yann@2077: each patch in its own email, all ordered in the way you entered them (oldest yann@2077: first). The command line flag --outgoing selects all changesets that are in yann@2077: your local but not yet in the upstream repository. Here, these are exactly yann@2077: the ones you entered into your local patch queue in the section above, so yann@2077: --outgoing is what you want. yann@2077: yann@2077: Each email gets the subject set to: "[PATCH x of n] " yann@2077: where 'x' is the serial number in the email series, and 'n' is the total number yann@2077: of patches in the series. The body of the email is the complete patch, plus yann@2077: a handful of metadata, that helps properly apply the patch, keeping the log yann@2077: message, attribution and date, tracking file changes (move, delete, modes...) yann@2077: yann@2077: `hg email` also threads all outgoing patch emails below an introductory yann@2077: message. You should use the introductory message (command line flag --intro) yann@2077: to describe the scope and motivation for the whole patch series. The subject yann@2077: for the introductory message gets set to: "[PATCH 0 of n] " yann@2077: and you get the chance to set the . yann@2077: yann@2077: Here is a sample `hg email` complete command line: yann@2077: Note: replace " (at) " with "@" yann@2077: yann@2077: hg email --outgoing --intro \ yann@2908: --to '"Yann E. MORIN" ' \ yann@2077: --cc 'crossgcc (at) sourceware.org' yann@2077: yann@2077: # It then opens an editor and lets you enter the subject yann@2077: # and the body for the introductory message. yann@2077: yann@2077: Use `hg email` with the additional command line switch -n to yann@2077: first have a look at the email(s) without actually sending them. yann@2077: yann@2077: yann@2077: MAINTAINING YOUR PATCHES: yann@2077: yann@2077: When the patches are refined by discussing them on the mailing list, yann@2077: you may want to finalize and resend them. yann@2077: yann@2077: The mq extension has the idiosyncrasy of imposing a stack onto the queue: yann@2077: You can always reedit/refresh only the patch on top of stack. yann@2077: The queue consists of applied and unapplied patches yann@2077: (if you reached here via the above steps, all of your patches are applied), yann@2077: where the 'stack' consists of the applied patches, and 'top of stack' yann@2077: is the latest applied patch. yann@2077: yann@2077: The following output of `hg qseries` is now used as an example: yann@2077: 0 A short_patch_name1 yann@2077: 1 A short_patch_name2 yann@2077: 2 A short_patch_name3 yann@2077: 3 A short_patch_name4 yann@2077: yann@2077: You are now able to edit patch 'short_patch_name4' (which is top of stack): yann@2077: yann@2077: # and execute again yann@2077: hg qrefresh -D [-e] yann@2077: yann@2077: yann@2077: If you want to edit e.g. patch short_patch_name2, you have to modify yann@2077: mq's stack so this patch gets top of stack. yann@2077: For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`. yann@2077: yann@2077: hg qgoto short_patch_name2 yann@2077: # The patch queue should now look like yann@2077: hg qseries yann@2077: 0 A short_patch_name1 yann@2077: 1 A short_patch_name2 yann@2077: 2 U short_patch_name3 yann@2077: 3 U short_patch_name4 yann@2077: # so patch # 1 (short_patch_name2) is top of stack. yann@2077: yann@2077: # and execute again yann@2077: hg qrefresh -D [-e] yann@2077: yann@2077: # the following command reapplies the now unapplied two patches: yann@2077: hg qpush -a yann@2077: # you can also use `hg qgoto short_patch_name4` to get there again. yann@2077: yann@2077: yann@2077: RESENDING YOUR REEDITED PATCHES: yann@2077: yann@2077: By mailing list policy, please resend your complete patch series. yann@2077: --> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set. yann@2077: yann@2077: yann@2077: SYNCING WITH UPSTREAM AGAIN: yann@2077: yann@2077: You can sync your repo with upstream at any time by executing yann@2077: # first unapply all your patches: yann@2077: hg qpop -a yann@2077: # next fetch new changesets from upstream yann@2077: hg pull yann@2077: # then update your working copy yann@2077: hg up yann@2077: # optionally remove already upstream integrated patches (see below) yann@2077: hg qdelete yann@2077: # and reapply your patches if any non upstream-integrated left (but see below) yann@2077: hg qpush -a yann@2077: yann@2077: Eventually, your patches get included into the upstream repository yann@2077: which you initially cloned. yann@2077: In this case, before executing the hg qpush -a from above yann@2077: you should manually "hg qdelete" the patches that are already integrated upstream. yann@2077: yann@2077: antony@2564: HOW TO FORMAT COMMIT MESSAGES (aka patch descriptions): yann@2077: yann@2077: Commit messages should look like (without leading pipes): yann@2077: |component: short, one-line description yann@2077: | yann@2077: |optional longer description yann@2077: |on multiple lines if needed titus@2571: | titus@2571: |Signed-off-by: as documented in section 7 of ct-ng's documentation yann@2077: titus@2571: Here is an example commit message (see revision 8bb5151c5b01): titus@2571: kernel/linux: fix type in version strings titus@2571: titus@2571: I missed refreshing the patch before pushing. :-( titus@2571: yann@2908: Signed-off-by: "Yann E. MORIN"