## thawedlib-tome.api
# Compiled by:
# src/app/makelib/makelib.sublib# Overview comments are at bottom of file.
# This api is implemented in:
# src/app/makelib/compilable/thawedlib-tome.pkgstipulate
package ad = anchor_dictionary; # anchor_dictionary is from src/app/makelib/paths/anchor-dictionary.pkg package ctl = global_controls; # global_controls is from src/lib/compiler/toplevel/main/global-controls.pkg package err = error_message; # error_message is from src/lib/compiler/front/basics/errormsg/error-message.pkg package mds = module_dependencies_summary; # module_dependencies_summary is from src/app/makelib/compilable/module-dependencies-summary.pkg package ms = makelib_state; # makelib_state is from src/app/makelib/main/makelib-state.pkg package pp = standard_prettyprinter; # standard_prettyprinter is from src/lib/prettyprint/big/src/standard-prettyprinter.pkg package raw = raw_syntax; # raw_syntax is from src/lib/compiler/front/parser/raw-syntax/raw-syntax.pkg package sci = sourcecode_info; # sourcecode_info is from src/lib/compiler/front/basics/source/sourcecode-info.pkg package shm = sharing_mode; # sharing_mode is from src/app/makelib/stuff/sharing-mode.pkg package sm = line_number_db; # line_number_db is from src/lib/compiler/front/basics/source/line-number-db.pkg package syx = symbolmapstack; # symbolmapstack is from src/lib/compiler/front/typer-stuff/symbolmapstack/symbolmapstack.pkg package sy = symbol; # symbol is from src/lib/compiler/front/basics/map/symbol.pkg package sys = symbol_set; # symbol_set is from src/app/makelib/stuff/symbol-set.pkg package ts = timestamp; # timestamp is from src/app/makelib/paths/timestamp.pkgherein
api Thawedlib_Tome {
#
Thawedlib_Tome;
Key = Thawedlib_Tome;
Plaint_Sink = err::Plaint_Sink;
Source_Code_Region = sm::Source_Code_Region;
Inlining_Request = ctl::inline::Localsetting;
Sourcefile_Syntax # Left in place because someday we may support, say, lisp(ish) and/or prolog(ish) sourcecode syntax. Or SML!
=
MYTHRYL | NADA;
Attributes # Except for "inlining", these are all deep magic used internally for bootstrapping.
=
{ crossmodule_inlining_aggressiveness: Inlining_Request, # This gets used in src/lib/compiler/back/top/improve/do-crossmodule-anormcode-inlining.pkg #
is_runtime_package: Bool, # Is this the 'runtime' package, requiring a special hack? See src/lib/core/init/runtime.pkg noguid: Bool,
#
explicit_core_symbol: Null_Or( sy::Symbol ), # Deep bootstrap magic for the "Core" / "_Core" package.
extra_static_compile_dictionary: Null_Or( syx::Symbolmapstack ) # See bottom-of-file comments.
};
Controller
=
{ save_controller_state: Void -> Void -> Void, # Generate a thunk containing current controller state, which when run will restore controller to that state.
set: Void -> Void
};
Info_Args # Argument to the make and make' calls which create Thawedlib_Tome instances.
=
{ sourcepath: ad::File, # File containing source code which compiles to produce .compiled in question.
#
library: ( ad::File,
Source_Code_Region
),
#
pre_compile_code: Null_Or( String ), # Literal source code to compile+run before compiling .compiled file in question
postcompile_code: Null_Or( String ), # Literal source code to compile+run after compiling .compiled file in question
is_local: Bool,
controllers: List( Controller ), # Save/set/restore some controller settings for duration of compiling this .compiled.
#
sharing_request
:
shm::Request
};
same_thawedlib_tome: (Thawedlib_Tome, Thawedlib_Tome) -> Bool; # Compare thawed compilables for equality.
compare: (Thawedlib_Tome, Thawedlib_Tome) -> Order; # Compare thawed compilables for ordering.
# The idea behind "new_generation" is the following:
#
# Before parsing .lib files (on behalf of makelib::make/compile or make_compiler::make_compiler etc.)
# we start a new generation.
#
# While parsing, when we encounter a new sourcefile we re-use existing
# information and bump its generation to "now".
#
# After we are done with one library we can safely evict
# all info records for files in this library if their generation
# is not "now".
#
# Moreover, if we encounter an entry that has a different owner library,
# we can either signal an error (if the generation is "now" which means
# that the file was found in another library during the same parse) or
# issue a "switched libraries" warning (if the generation is not
# 'now' which means that the file used to be in another library):
#
new_generation
:
Void -> Void;
make_thawedlib_tome
:
(Inlining_Request, Bool)
->
ms::Makelib_State
->
Info_Args
->
Thawedlib_Tome;
make_thawedlib_tome'
:
Attributes
->
ms::Makelib_State
->
Info_Args
->
Thawedlib_Tome;
error: ms::Makelib_State -> Thawedlib_Tome -> Plaint_Sink;
exports: ms::Makelib_State -> Thawedlib_Tome -> Null_Or( sys::Set );
module_dependencies_summary: ms::Makelib_State -> Thawedlib_Tome -> Null_Or(mds::Declaration);
find_raw_declaration_and_sourcecode_info
:
ms::Makelib_State
->
# Prettyprint symbol table and function:
Null_Or (
( syx::Symbolmapstack,
(
( syx::Symbolmapstack,
Null_Or( sci::Sourcecode_Info )
)
->
pp::Prettyprinter
->
( raw::Declaration,
Int
)
->
Void
) )
)
->
Thawedlib_Tome
->
Null_Or( (raw::Declaration, sci::Sourcecode_Info) );
make_compiledfile_name: Thawedlib_Tome -> String;
set_compiledfile_version: (Thawedlib_Tome, String) -> Void;
get_compiledfile_version: Thawedlib_Tome -> String; # Returns something like "version-$ROOT/src/app/makelib/(makelib-lib.lib):compilable/thawedlib-tome.pkg-1187780741.285"
sourcepath_of: Thawedlib_Tome -> ad::File;
sourcefile_syntax_of: Thawedlib_Tome -> Sourcefile_Syntax;
group_of: Thawedlib_Tome -> ad::File;
attributes_of: Thawedlib_Tome -> Attributes;
module_dependencies_summaryfile_name_of:Thawedlib_Tome -> String;
sourcefile_timestamp_of: Thawedlib_Tome -> ts::Timestamp;
pre_compile_code_of: Thawedlib_Tome -> Null_Or(String);
postcompile_code_of: Thawedlib_Tome -> Null_Or(String);
controllers_of: Thawedlib_Tome -> List(Controller);
is_local: Thawedlib_Tome -> Bool;
sharing_request_of: Thawedlib_Tome -> shm::Request;
get_sharing_mode: Thawedlib_Tome -> shm::Mode;
set_sharing_mode: (Thawedlib_Tome, shm::Mode) -> Void;
forget_raw_declaration_and_sourcecode_info
:
Thawedlib_Tome -> Void; # Forget a parse tree that we are done with.
clean_library: Bool -> ad::File -> Void;
#
# Evict all elements that belong to a given library but which
# are not of the current generation. "clean_library" should be
# called right after completing parsing of the .lib file.
# If the boolean flag ("now_built") is set to TRUE, then all
# members of the library are dismissed regardless of their
# generation. This is used to get rid of the information for
# members of now-built libraries.
is_known: Thawedlib_Tome -> Bool; # See if a given piece of info is (still) known here. (Is this a corruption of "is_now"? XXX BUGGO FIXME)
clear_state: Void -> Void; # Delete all known info.
# Different ways of describing a mythryl file using library and source:
#
describe_thawedlib_tome: Thawedlib_Tome -> String; # Something like "src/lib/reactive/(reactive.lib):reactive.pkg" or "src/lib/x-kit/(xkit.lib):xclient/(xclient.sublib):(xclient-internals.sublib):src/color/rgb.pkg"
error_location: ms::Makelib_State -> Thawedlib_Tome -> String;
};
end;
# MOTIVATION AND OVERVIEW
#
# Unlike most contemporary compilers, the Mythryl
# compiler treats parsing and compiling as separate
# operations, performed at different times by different
# code for different reasons. Accordingly, a Mythryl
# source file may exist in three principal states:
#
# 1) Not yet parsed or compiled.
# 2) Parsed but not yet compiled.
# 3) Both parsed and compiled.
#
# Compiling a "foo.pkg" source file produces a
# "foo.pkg.compiled" object-code file. This .compiled file
# may then either be left bare on disk, or combined
# with other .compiled files in a library -- a "freezefile".
#
# The
#
# Thawedlib_Tome
#
# records we implement in this file serve as our
# primary representation for source files at any
# stage of compilation. By design, thus, they
# can be created before we have parsed or compiled
# the sourcefile in question.
#
# The parsetree, once obtained, is added to the
# thawedlib_tome record by setting its 'parsetree' refcell.
#
# Most other information is recorded by setting
# up datastructures with Thawedlib_Tome records as
# keys and other information as matching values.
#
# In particular, the 'symbol_and_inlining_mapstacks_map' map in
# src/app/makelib/compile/compile-in-dependency-order-g.pkg# uses Thawedlib_Tome records as keys to represent
# what we know about a sourcefile before compilation,
# and Symbol_And_Inlining_Mapstacks values to represent
# what we learn about a sourcefile by compiling it.
#
#
# FROZEN libraries present a special case, since we
# never recompile their contents, and we do not assume
# that the corresponding source code is still available.
# This makes Thawedlib_Tome records inappropriate for
# representing the .compiled files within them, so we instead
# use the alternate
#
# Frozenlib_Tome
#
# records implemented in
#
# src/app/makelib/freezefile/frozenlib-tome.pkg#
# Consequently, just about all code dealing with .compiled
# files has two cases, one to handle Thawedlib_Tome
# records and one to handle Frozenlib_Tome records.
#
# Together, these two record types form the prime
# objects of interest for the dependency graphs which
# drive our 'makelib' functionality, since we understand
# all code dependencies ultimately in terms of dependency
# edges between these two types of records.
#
# Our intra- and inter-library dependency graphs are defined in
#
# src/app/makelib/depend/intra-library-dependency-graph.pkg# src/app/makelib/depend/inter-library-dependency-graph.pkg#
# respectively.
#
# Thawedlib_Tome records contain only information that does
# not require running the machine-dependent part of the
# compiler, and consequently are platform-agnostic: They
# may be shared by all our backends.
#
#
# 'setup'
# is a hack to support the makelib 'tool' subsystem.
# It consists of two (optional) literal strings of
# Mythryl code to be compiled and run immediately before
# the main module code.
#
# The idea is that these scraps of code may be used
# for such things as:
# o Turning on special debug checks,
# o Turning off obnoxious compiler diagnostics, or
# o Setting the code-optimizer specially for a particular file.
#
#
# 'controller'
# This stuff seems to be support for some makelib 'tool'
# hack letting one specifically change some controller
# settings for the duration of the compile of a particular
# .compiled file. ("controllers" are what we use to implement
# Unix commandline switches and such.)
#
# This (apparently undocumented) mechanism is a lot
# like the various emacs "save-excursion" constructs
# in that it:
# o Saves the current value of some controller.
# o Sets a new value for that controller.
# o Compiles the .compiled file in question.
# o Restores the original value of that controller.
#
# 'extra_static_compile_dictionary':
# This is a bootstrapping hack used in
# src/app/makelib/mythryl-compiler-compiler/process-mythryl-primordial-library.pkg# to give selected packages (namely those flagged "primitive" in
# src/lib/core/init/init.cmi
# access to
# base_types_and_ops::base_types_and_ops
# from
# src/lib/compiler/front/semantic/symbolmapstack/base-types-and-ops.pkg# This field will be NULL for all vanilla packages.
## (C) 1999 Lucent Technologies, Bell Laboratories
## Author: Matthias Blume (blume@kurims.kyoto-u.ac.jp)
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.