diff options
author | Mike Gerwitz <mike.gerwitz@ryansg.com> | 2020-02-26 11:26:15 -0500 |
---|---|---|
committer | Mike Gerwitz <mike.gerwitz@ryansg.com> | 2020-03-02 15:54:36 -0500 |
commit | c2e6efc0b5c37e172485a2ec0adaafda4b6a4179 (patch) | |
tree | cbdf9e86c14bd6a1bbc478db04e2b0a58537e116 | |
parent | 310ddb7ea81fa5a1c05c423127e0d30adbcd892d (diff) | |
download | tame-c2e6efc0b5c37e172485a2ec0adaafda4b6a4179.tar.gz tame-c2e6efc0b5c37e172485a2ec0adaafda4b6a4179.tar.bz2 tame-c2e6efc0b5c37e172485a2ec0adaafda4b6a4179.zip |
TAMER: Additional crate::ld documentation
-rw-r--r-- | tamer/src/ld.rs | 76 |
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; |