import Miranda 2.066 from upstream

1 files changed, 132 insertions, 0 deletions

diff --git a/miralib/manual/27/5 b/miralib/manual/27/5
new file mode 100644
index 0000000..22e4753
--- /dev/null
+++ b/miralib/manual/27/5
@@ -0,0 +1,132 @@
+_S_e_p_a_r_a_t_e_ _c_o_m_p_i_l_a_t_i_o_n_ _a_n_d_ _`_._x_'_ _f_i_l_e_s
+
+The  Miranda  compiler  compiles  to  an  intermediate  code,  based  on
+combinators.   When a Miranda expressions are evaluated in the course of
+a session this code is executed by an interpreter.
+
+Since compilation is a  complex  process  (involving  lexical  analysis,
+parsing, type checking and code-generation, as well as a number of other
+minor steps) it is undesirable that the results of  compiling  a  script
+should  just  be  "thrown  away"  at  the  end  of  a session.  To avoid
+unnecessary acts  of  recompilation  the  Miranda  system  maintains  an
+object-code  file  in  association  with  each  source file containing a
+Miranda script.
+
+For each source file, called say `script.m',  the  Miranda  system  will
+create an object code file, called `script.x'.  No action is required by
+the user to keep these files up-to-date, since this  is  taken  care  of
+automatically by the Miranda system.  The .x files are never referred to
+directly by the Miranda user, and you should not try to edit them  (they
+contain  binary  data).
+
+You may however safely remove any .x file (if for example you don't wish
+it  to  use  up  filespace)  since  this will at worst cause the Miranda
+compiler to do some extra work later to recreate it.
+
+If you select a script as the current script of a Miranda  session,  and
+it  has  an  up-to-date  .x  file, this will be loaded instead, avoiding
+recompilation.  If the .x file does not exist, or _a_n_y_ _ _r_e_l_e_v_a_n_t_ _ _s_o_u_r_c_e_ 
+_f_i_l_e_ _h_a_s_ _b_e_e_n_ _m_o_d_i_f_i_e_d since the .x file was created, the script will be
+recompiled (and a side effect of your having selected this  source  file
+as  the  current script will be to bring into existence an up-to-date .x
+file for it).
+
+[Inductive definition - source file B is `relevant' to source file A iff
+file  A %inserts or %includes B or any file to which B is relevant.  For
+a discussion of `%include' and the other library directives  see  manual
+sections on `The Library Mechanism'.]
+
+Note that compiling a script containing %include  statements  will  have
+the  side  effect of triggering subsidiary compilation processes for any
+relevant source files which have been modified since their corresponding
+.x  file  was created.  Users familiar with the UNIX program `make' will
+recognise this process as essentially the same  as  that  which  happens
+when a `makefile' is obeyed.  In the case of Miranda however, the `make'
+process is fully automated by being built into the compiler.
+
+_M_o_r_e_ _a_d_v_a_n_c_e_d_ _i_n_f_o_r_m_a_t_i_o_n
+
+If you want to check that a  given  Miranda  script  has  an  up-to-date
+object  code  file  _w_i_t_h_o_u_t  entering  a  Miranda  session,  this can be
+accomplished from UNIX by calling mira with a special flag, thus
+	mira -make script.m
+
+will force the existence of an  up-to-date  `script.x',  performing  all
+(and only) those compilations which are necessary.  Any number of source
+files can be given after  the  -make  flag  (and  as  usual  if  a  `.m'
+extension is omitted it will be added automatically).
+
+Example:- to make  sure  every  Miranda  source  file  in  your  current
+directory has an up-to-date object code file, say `mira -make *.m'.
+
+Applying mira -make to a `.x' file is equivalent to applying it  to  the
+corresponding `.m' file.  So another way to make sure everything in your
+current directory is up-to-date is to say `mira -make  *.x'.   This  has
+the  advantage  that it will also remove any `.x' files whose `.m' files
+no longer exist.
+
+In the best UNIX tradition mira -make  does  its  work  silently  unless
+something  is wrong.  If the source files are all correct closed scripts
+with up-to-date  `.x'  files,  mira  -make  says  nothing  at  all.   If
+recompilations are necessary it informs you which source files are being
+compiled, and, as a last step, the names of any  scripts  which  contain
+errors or undefined names are listed, to stdout.
+
+The exit status  of  a  `mira  -make'  (relevant  if  you  are  a  shell
+programmer,  or wish to include a `mira -make' command in a makefile for
+a larger setup) is as follows.  If (AFTER any  necessary  recompilations
+have  been  performed)  all the source files have up-to-date `.x' files,
+and do not contain any syntax errors, type errors,  or  undefined  names
+(these  facts  are  recorded  in  .x files) the exit status will be zero
+(=ok), otherwise it will be 1.
+
+It is possible to find out what names are  exported  from  one  or  more
+Miranda scripts without entering a Miranda session by using the command
+	mira -exports files
+(as  always  the `.m' extension is added automatically to each filename,
+if missing).  This command first calls `mira -make'  on  each  file,  to
+make  sure everything is uptodate, and then lists to standard output the
+exported names together with their types (one per line).  If  more  than
+one  file  is specified each group of names will be preceded by the name
+of the file to which they appertain.
+
+Note that the export profile of a script includes information about  its
+free identifiers (if any).
+
+It is also possible to find out the names of all files on which a  given
+set  of  Miranda scripts depend, via %include and %insert statements, by
+using the command
+	mira -sources files
+This lists to standard output, one per line, the names of  all  relevant
+source  files.   The  standard  environment, <stdenv>, is always omitted
+from the list.
+
+_E_f_f_e_c_t_ _o_f_ _`_m_v_'_ _a_n_d_ _`_r_m_'
+ Finally we note a couple of points about the behaviour  of  Miranda  .x
+files under applications of mv and rm to their corresponding sources.
+
+A `.x' file records (inter alia) the names of all relevant source  files
+relative  to  the  directory  in which it is stored, together with their
+`date and time last modified'.  Note that the UNIX command `mv' does not
+alter the time-last-modified of the file being moved.  So it is possible
+when moving a miranda source file (or a group of  interdependant  source
+files)  from  one  directory  to  another  to  save  mira  the bother of
+recompiling them, simply by moving all the relevant `.x' files into  the
+new directory along with the sources.  (This doesn't work however if you
+change the name of any of the source files during the move.)
+
+[Note that `tar' has  the  same  property,  so  the  up-to-date-ness  of
+Miranda .x files is preserved across a tape dump.]
+
+If you use `rm' to remove a Miranda  source  file,  the  next  time  you
+invoke  mira  with the (now non-existent) file as its current script, it
+will promptly remove the corresponding `.x' file.  The logic of this  is
+as  follows:- `.x' files must be kept up-to-date with their sources, and
+the way to make a `.x' file up-to-date with a non-existent source is  to
+make  it  too non-existent.  As a consequence it is not possible to send
+someone a Miranda object code  file  without  the  corresponding  source
+(mira will delete it as soon as they try to use it!).
+
+From some points of view this last feature might be regarded as a bug  -
+a way round it may be provided in a later release of the Miranda system.
+