Mike Gerwitz

Activist for User Freedom

diff options
1 files changed, 69 insertions, 7 deletions
diff --git a/tamer/src/ld.rs b/tamer/src/ld.rs
index defc5a9..66908b3 100644
--- a/tamer/src/ld.rs
+++ b/tamer/src/ld.rs
@@ -15,18 +15,29 @@
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
-//! The [linker][] is responsible for combining individually compiled
-//! [object files][] into a final executable.
+//! Combine [object files](crate::obj) into a final executable.
-//! It's user-facing binary is [`tameld`][tameld].
+//! It's user-facing binary is [`tameld`](../../tameld).
-//! **TODO:** More information.
+//! Background Information
+//! ======================
+//! A [linker][] is responsible for combining individually compiled
+//! [object files](crate::obj) containing relocatable code into a final
+//! executable.
+//! This involves putting the compiled code fragments into the right order
+//! and into the right place within the executable.
//! [linker]: https://en.wikipedia.org/wiki/Linker_(computing)
-//! [object files]: https://en.wikipedia.org/wiki/Object_file
-//! [tameld]: ../../tameld
-//! Backwards-Compatibility (XSLT System)
+//! _See below for more information on why this linker currently produces
+//! another intermediate format (`xmle`) rather than a final executable._
+//! The type of relocatable code depends on the _target_.
+//! Currently, the only target is JavaScript.
+//! Backwards-Compatibility With XSLT System
//! -------------------------------------
//! This linker is part of the TAMER (TAME in Rust) project,
//! which aims to incrementally rewrite TAME in Rust.
@@ -44,5 +55,56 @@
//! the `xmle` file is still needed for other purposes,
//! such as `summary` and `dote` generation.
//! Those too will eventually be linker targets.
+//! Linking Process
+//! ===============
+//! The linker works in the following steps:
+//! 1. [Object files](crate::obj) are recursively read.
+//! They are used in a streaming manner for the next step of the
+//! process;
+//! they do not persist in memory.
+//! Only the required portions of the file are loaded.
+//! See the [Legacy IR](crate::ir::legacyir) for more information.
+//! 2. This information is used to populate the [ASG].
+//! Information is added to the graph as it is discovered during object
+//! file loading,
+//! so the graph initially contains edges to missing identifiers.
+//! Expressions are _not_ added to the graph,
+//! as they are not needed for linking.
+//! Once all data are loaded,
+//! the ASG contains relocatable code fragments for each identifier.
+//! 3. The ASG is [sorted topologically][topo-sort] so that dependencies
+//! will be written to the executable file before identifiers that
+//! depend on them.
+//! Roots for the sort are specified by the return map.
+//! _Identifiers that are not accessable from one of those roots will be
+//! omitted from the executable output._
+//! 4. Relocatable code fragments are output into various sections in the
+//! executable file.
+//! This output file is currently `xmle`.
+//! (**TODO**: Link to new `xmle` crate.)
+//! [ASG]: crate::ir::asg
+//! [topo-sort]: https://en.wikipedia.org/wiki/Topological_sorting
+//! Steps 1 and 2 are performed at the same time:
+//! object files are used to immediately populate the [ASG][].
+//! Since the ASG contains only partial information,
+//! it must perform other validations (such as extern resolution) during
+//! this process;
+//! see [crate::ir::asg] for more information.
+//! Because the topological sort only considered explicitly defined roots,
+//! identifiers are only included in the final executable if they are
+//! either a root or are a dependency of a root.
+//! This makes it possible to create large reusable packages without
+//! incurring a runtime cost for unused objects,
+//! which is especially important since templates may expand into many
+//! identifiers.
pub mod poc;