<Chapter id="Chapter.Linker" proglang=sh>
  <Title/The Oz Linker: <code/ozl//

    <P>
      Application development can be considerably eased by splitting
      the application in a large number of orthogonal and reusable
      functors. However, deployment of an application gets harder in
      the presence of a large number of functors:
    </P>
    
    <P>
      <List>
        <Item>Installing the application requires correct installation
        of a large number of functors.
        <Item>Execution might be slow due to frequent file- or even
        network accesses.
      </List>
    </P>
    
    <P>
      The commandline tool <Kbd/ozl/ eases deployment by creating a
      new functor that includes imported functors in a prelinked
      fashion: it is possible to collapse a hierarchy of functors into
      a single equivalent one. The model that should be kept in mind,
      is that the newly created functor employs an internal, private
      module manager that excutes the toplevel
      application functor together with all included functors.
    </P>

    <P>
      A short introduction by means of examples can be found in
      <ptr.extern to="ozdoc:apptut" key="section.deployment.linking">.
    </P>

  <Section id="Section.Linker.Basic">
    <Title/Basic Usage/

    <P>
      The linker can be invoked on the input functor <Var/In/ in order
      to create an output functor <Var/Out/ as follows:
      <<<% ozl <Var/In/ -o <Var/Out/>>>
    </P>

    <P>
      Consider for example the pickled functors <File/A.ozf/,
      <File/B.ozf/, and <File>subdir/C.ozf</File>, where <File/A.ozf/
      has been created from the following functor definition:
<Code display proglang=oz>functor
import B
       C at 'subdir/C.ozf'
       Application
end</Code>
      and the other functors have empty imports.
      By executing
      <<<% ozl A.ozf -o D.ozf>>>
      a new pickled functor <File/D.ozf/ is created that contains 
      both the functors contained in <File/B.ozf/ and
      <File>subdir/C.ozf</File> but not the system functor <Code
      proglang=oz/Application/.
    </P>

    <P>
      If the linker is invoked in verbose mode as
      <<<% ozl --verbose A.ozf -o D.ozf>>>
      or
      <<<% ozl -v A.ozf -o D.ozf>>>
      for short, it prints the following information on which functors
      are in fact included and which are still imported by the newly
      created functor.
<Code display proglang=fundamental>
Include:
   A.ozf, B.ozf, subdir/C.ozf.
Import:
   x-oz://system/Application.
</Code>
     </P>
     
     <P> 
       If we now invoke the linker on the newly created pickled
       functor <File/D.ozf/ in verbose mode as follows:
       <<<% ozl -v D.ozf>>>
       it only prints the following information without creating a new
       functor:
<Code display proglang=fundamental>
Include:
   D.ozf.
Import:
   x-oz://system/Application.
</Code>
     </P>
     
     <P>
       By default, the linker includes (or links) all functors that
       are referred to by relative urls as in our previous example. How
       to change this behaviour is discussed in <Ptr
       to="Section.Linker.Include">.
     </P>      

  </Section>

  <Section id="Section.Linker.Include">
    <Title/Including and Excluding Functors/

    <P>
      <List>
        <Entry><<--relative>>
        <Synopsis><<--relative>> (default), <<--norelative>>
        <Item>
           All functors that are referred to by relative urls are
           included.  Import urls in the resulting functor remain
	   relative.

        <Entry><<--include>>
        <Synopsis><<--include=<Var/URL/,&ellipsis,<Var/URL/>>
        <Item>
           Include all functors whose url matches one of the comma
           separated url prefixes.
        
        <Entry><<--exclude>>
        <Synopsis><<--exclude=<Var/URL/,&ellipsis,<Var/URL/>>
        <Item>
           Exclude all functors whose url matches one of the comma
           separated url prefixes.

	<Entry><<--rewrite>>
	<Synopsis><<--rewrite=<Var/RULE/,&ellipsis,<Var/RULE/>>
	<Item>
	   When the functors are gathered that make up the linked functor,
	   all import URLs are resolved with respect to the importing
	   functor.  This means that all file urls become absolute, and
	   as such make up the import of the output functor.
	<P>
	   This is often not desirable.  In the common case that the
	   imported functors lie in the same directory or in subdirectories
	   as the root functor, the <<--relative>> option can be used, in
	   which case the import urls remain relative.
	<P>
	   The <<--rewrite>> option generalizes this principle:  It allows
	   to specify a list of rules of the form << <Var/FROM/=<Var/TO/>>,
	   meaning:  If a url has prefix <Var/FROM/, then replace it by
	   <Var/TO/.  The first matching rule is applied.
      </List>
    <P>

    <P>
      Note that multiple <<--include>> and <<--exclude>> directives
      can be given on the commandline.  They have cummulative effect,
      with the policy that later directives take precedence over earlier
      ones.  For example:
<code display proglang=sh>
ozl --include=/foo/ --exclude=/foo/bar/ ...
</code>
      causes all imports from files below directory <file>/foo</file> to
      be included except those under directory <file>/foo/bar</file>.  We
      can further refine this policy by introducing an exception to the
      last exclusion pattern and request inclusion of modules imported
      from below directory <file>/foo/bar/baz</file>:
<code display proglang=sh>
ozl --include=/foo/ --exclude=/foo/bar/ --include=/foo/bar/baz/ ...
</code>
    </P>

  </Section>

  <Section id="Section.Linker.Pickling">
    <Title/Pickling Options/

    <P>
      The linker supports the following default options for pickles.
    </P>

    <P>
      <List>
        <Entry><<--compress>>
        <Synopsis><<--compress=<Var/N/>>, <<-z <Var/N/>>
        <Item>
           The created pickle is compressed with level
           <Var/N/ (a single digit). By default the compression level
           <Var/N/ is <<0>>, that is, no compression is employed. 

        <Entry><<--executable>>
        <Synopsis><<--executable>> (<<-x>>), <<--noexecutable>> (default)
        <Item>
           Output the pickled functor as being executable (that is,
           with an additional header).
        
	<entry/<code/--execheader=?{STRING}//
	<item>When invoked with option <code/-x/ the linker first
outputs a header so that the output file may be interpreted by
the operating system as an executable.  Under Unix, the default behaviour
is to use the following as header:
<code display>
#!/bin/sh
exec ozengine $0 "$@"
</code>
The <code/--execheader/ option allows you to specify a different
header.</item>

	<entry/<code/--execpath=?{STRING}//
	<item>Uses the header given above in the description of
<<--execheader>>, except that <file/ozengine/ is replaced by ?{STRING}.

	<entry/<code/--execfile=?{FILE}//
	<item>Reads in ?{FILE} and uses this as header.
Under Windows, the default behaviour is to use the file provided in
?{ozhome}<file>/bin/ozwrapper.bin</file>, where ?{ozhome} is Mozart's
installation folder.  <File/ozwrapper.bin/ is a Windows executable
that launches <file/ozengine/.

	<entry/<code/--execwrapper=?{FILE}//
	<item>Reads in ?{ozhome}<file>/bin/</file>?{FILE} and uses it
as header for executable files.  Apart from <file/ozwrapper.bin/,
an <file/ozwrapperw.bin/ is supplied that launches <file/ozenginew/
instead of <file/ozengine/.  This option provides a convenient way to
use this alternative wrapper.

        <entry/<code/--target=unix/, <code/--unix//
	<entry/<code/--target=windows/, <code/--windows//
	<item/When creating an executable functor, do it for the specified
target platform rather than for the current host platform./

      </List>
    <P>

  </Section>

  <Section id="Section.Linker.Misc">
    <Title/Miscellaneous Options/

    <P>
      <List>
        <Entry><<--sequential>>
        <Synopsis><<--sequential>>, <<--nosequential>> (default)
        <Item>
           Do not create a thread per executed functor body, rather
           execute all functor bodies in the same thread in a bottom
           up fashion.
        <P class=danger>
           Use with care! In case the functors included have cyclic
           imports, it is not used.
        </P>
        

      </List>
    <P>

  </Section>

</Chapter>

