Document by Luca Bruno & Sylvestre Ledru

This source package is unfortunately quite tricky and with
several cutting edges, due to the complexity of rust-lang
bootstrapping system and the high rate of language changes
still ongoing.

We try to describe here inner packaging details and the
reasons behind them.


Bootstrapping
=============

This package is composed of two upstream tarballs:
 * the rust-lang source
 * a minimal stage0 to start bootstrapping the system

This is an interim solution, in the long term we plan to have
rust bootstrap itself from an installed copy. However, we are 
currently forced to ship a stage0.

We have to that way, because:
 * upstream periodically snapshots stage0. This happens multiple times 
   between releases, so it is not currently possible to bootstrap using
   (only) released versions
 * requirements are pretty tight, and when a language feature change
   rustc cannot self-bootstrap (you need a stage0 before the change,
   which support the old set of features)
 * stage0 are in strictly-chained linear series. This means we cannot 
   miss even a single snapshot, otherwise next bootstrap could fail.
   Moreover, also due to first point above, bootstrapping across 
   non-adjacent snapshots/packages won't work

On the other hand:
 * stage0 is directly generated by the same infrastructure that
   packages the source tarball
 * Mozilla upstream directly provides it, and at least has some point 
   you have to trust it in order to break the boostrap cycle
 * builds are automated, and public build logs can be inspected at
   http://buildbot.rust-lang.org/builders/snap3-linux
 * snapshot artifacts have to be manually approved by upstream, and
   are identified by the SHA1 of the resulting content

Things should improve as the language is being stabilized. 
We will re-evaluate this choice after 1.0.


Embedded libraries
==================

This source package embeds several external libraries (foeked and managed 
by rust upstream as git submodules).
In early stages, many more libraries were forked/emebedded but we are steadily
progressing in splitting them out.

Here below the remaining ones, with the technical reasons.

 * jemalloc from https://github.com/rust-lang/jemalloc
   -> system-wide one can't be used due to rust using a "je_" prefix.

   This is intentional upstream design and won't change soon, see:
    - https://github.com/rust-lang/rust/pull/18678
    - http://smallcultfollowing.com/babysteps/blog/2014/11/14/allocators-in-rust/

 * compiler-rt from https://github.com/rust-lang/compiler-rt
   -> system-wide compiler-rt fails during linkage

   Bug reported upstream, still to be fixed, see:
    - https://github.com/rust-lang/rust/issues/15054
    - https://github.com/rust-lang/rust/issues/15708

As a summary, we plan to:
 * keep embedding jemalloc (probably forever)
 * work with upstream to fix compiler-rt linkage soon.

 -- Sylvestre Ledru <sylvestre@debian.org>  Fri, 27 Mar 2015 14:27:12 +0100