<?xml version="1.0" encoding="utf-8" ?> <!-- for emacs: -*- coding: utf-8 -*- -->
<!-- Apache may like this line in the file .htaccess: AddCharset utf-8 .html -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg-flat.dtd" >
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head><title>installPackage -- load and install a package and its documentation </title>
<link rel="stylesheet" type="text/css" href="../../../../Macaulay2/Style/doc.css"/>
</head>
<body>
<table class="buttons">
<tr>
<td><div><a href="_loaded__Packages.html">next</a> | <a href="_load__Package.html">previous</a> | <a href="_loaded__Packages.html">forward</a> | <a href="_load__Package.html">backward</a> | <a href="_packages.html">up</a> | <a href="index.html">top</a> | <a href="master.html">index</a> | <a href="toc.html">toc</a> | <a href="http://www.math.uiuc.edu/Macaulay2/">Macaulay2 web site</a></div>
</td>
</tr>
</table>
<div><a href="index.html" title="">Macaulay2Doc</a> > <a href="___The_sp__Macaulay2_splanguage.html" title="">The Macaulay2 language</a> > <a href="_packages.html" title="">packages</a> > <a href="_install__Package.html" title="load and install a package and its documentation ">installPackage</a></div>
<hr/>
<div><h1>installPackage -- load and install a package and its documentation </h1>
<div class="single"><h2>Synopsis</h2>
<ul><li><div class="list"><dl class="element"><dt class="heading">Usage: </dt><dd class="value"><div><tt>installPackage PACKAGENAME</tt></div>
</dd></dl>
</div>
</li>
<li><div class="single">Inputs:<ul><li><span><tt>PACKAGENAME</tt>, a <a href="___String.html" title="the class of all strings">String</a> or <a href="___Package.html" title="the class of all packages">Package</a></span></li>
</ul>
</div>
</li>
<li><div class="single">Consequences:<ul><li>The package is installed in a local directory, so that in the future, one may simply use <a href="_load__Package.html" title="load a package">loadPackage</a>. Documentation for the package is also produced, running any Macaulay2 examples that are requested in the package documentation.</li>
</ul>
</div>
</li>
<li><div class="single"><a href="_using_spfunctions_spwith_spoptional_spinputs.html">Optional inputs</a>:<ul><li><span><tt>FileName => </tt><span><span>a <a href="___String.html">string</a></span>, <span>default value null</span>, the name of the file containing the source code of the package, from which it should be loaded</span></span></li>
<li><span><tt>UserMode => </tt><span><span>default value null</span>, if <a href="_true.html" title="">true</a>, then do not give the <tt>-q</tt> option to <tt>M2</tt> when running examples, thereby allowing it to load the user's <a href="_initialization_spfile.html" title="">initialization file</a>, allowing it to load packages previously installed in the user's <a href="_application__Directory.html">application directory</a>, and allowing packages it loads to read their configuration files from the the user's <a href="_application__Directory.html">application directory</a>. If <a href="_false.html" title="">false</a>, then do give the option. If <a href="_null.html" title="the unique member of the empty class">null</a>, then propagate the option from the current <a href="_command__Line.html" title="the command line arguments">commandLine</a>, if one occurs there.</span></span></li>
<li><span><tt>DebuggingMode => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value false</span>, whether to enter <a href="_the_spdebugger.html" title="">the debugger</a> if an error occurs during installation</span></span></li>
<li><span><tt>RerunExamples => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value false</span>, whether to rerun all the examples during installation</span></span></li>
<li><span><tt>RunExamples => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value true</span>, whether to run the examples during installation</span></span></li>
<li><span><tt>IgnoreExampleErrors => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value false</span>, whether to ignore errors that occur during the running of examples during installation</span></span></li>
<li><span><tt>CheckDocumentation => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value true</span>, whether to check the package's documentation for consistency and completeness</span></span></li>
<li><span><tt>MakeDocumentation => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value true</span>, whether to make the documentation for the package during installation</span></span></li>
<li><span><tt>MakeInfo => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value true</span>, whether to make the info pages. This is a form of the documentation that can be viewed using the Unix command <tt>info</tt> or using <tt>emacs</tt>.</span></span></li>
<li><span><tt>InstallPrefix => </tt><span>the installation prefix for installation of the files of the package, in case encapsulation is not enabled, or for installation of the links to the files, in case encapsulation is enabled. The value of this option can be a string or a function of no arguments returning a string. The default value is the subdirectory named <tt>local</tt> of the user's <a href="_application__Directory.html" title="the path to the user's application directory">application directory</a>.</span></span></li>
<li><span><tt>PackagePrefix => </tt><span>the installation prefix for installation of the files of the package in case encapsulation is enabled. The value of this option can be a string or a function of no arguments returning a string. The default value is the subdirectory named <tt>encap</tt> of the user's <a href="_application__Directory.html" title="the path to the user's application directory">application directory</a>.</span></span></li>
<li><span><tt>Encapsulate => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value false</span>, whether to encapsulate all the installed files in a subdirectory of the directory specified by the <tt>PackagePrefix</tt> option, whose name is specified by the <tt>EncapsulateDirectory</tt> option. Encapsulation makes it easy to delete all the files associated with a package (see <a href="_epkg.html" title="">epkg</a>). On the other hand, encapsulation involves the use of symbolic links, which are of limited utility in a Cygwin version of Macaulay2, because non-Cygwin programs don't understand them.</span></span></li>
<li><span><tt>EncapsulateDirectory => </tt><span>a string that gives the name of the encapsulation subdirectory, terminated with a <tt>/</tt>, in the case where the value of the <tt>Encapsulate</tt> option is <tt>true</tt>, or a function that accepts a package and returns such a string. The default function returns a string that has the form <tt>PACKAGENAME-VERSION</tt>, where <tt>VERSION</tt> is the version number specified by the package as value of the <a href="_new__Package_lp__String_rp.html" title="package item: start a new package">Version</a> option provided to <a href="_new__Package_lp__String_rp.html" title="package item: start a new package">newPackage</a>.</span></span></li>
<li><span><tt>MakeLinks => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value true</span>, whether to make links to the files after installing them, in case encapsulation is enabled</span></span></li>
<li><span><tt>AbsoluteLinks => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value true</span>, whether the links made should contain real absolute paths, rather than relative paths. If set to <a href="_true.html" title="">true</a>, the default value, then the files linked to should already exist, either under the current installation prefix, or in any of the directory trees listed in <a href="_prefix__Path.html" title="absolute locations of Macaulay2 files">prefixPath</a>. (The other files to be created as part of the installation of the current package will be made to exist (as empty files) in an earlier pass.) If the option is set to <a href="_false.html" title="">false</a>, then no absolute links will be made, and all references to documentation nodes will point to locations in the same directory tree, even though the corresponding files may not be there (yet). This behaviour is useful only when installing documentation in the main <em>Macaulay2</em> documentation tree (given by <a href="_prefix__Directory.html" title="the prefix directory">prefixDirectory</a>), or for preparing documentation that will eventually be installed there.</span></span></li>
<li><span><tt>RemakeAllDocumentation => </tt><span><span>default value true</span>, whether to regenerate all of the help pages for this package. The default action is to rebuild only the html pages of the documentation entries that have been changed since the last time the package was installed. However, some changes to an entry, such as to its headline, will change the html of other pages that cross-reference it.</span></span></li>
<li><span><tt>CacheExampleOutput => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value false</span>, whether to cache (newer) example output in a subdirectory of the <a href="_new__Package_lp__String_rp.html">auxiliary file directory</a> named <tt>examples</tt>, for use in a future installation. This value will override any value explicitly specified when <a href="_new__Package_lp__String_rp.html" title="package item: start a new package">newPackage</a> is called. After the directory is created, it will necessary for the user to specify <tt>AuxiliaryFiles=>true</tt> with the <a href="_new__Package_lp__String_rp.html" title="package item: start a new package">newPackage</a> command.</span></span></li>
<li><span><tt>SeparateExec => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value false</span>, whether to install the files of the package in two separate directory trees, one for the architecture independent files, and one for the architecture dependent files</span></span></li>
<li><span><tt>Verbose => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value true</span>, whether to display some details of the installation procedure. For even more information set <a href="_debug__Level.html" title="current level debugging">debugLevel</a> to a number greater than 0 or a number greater than 5.</span></span></li>
</ul>
</div>
</li>
</ul>
</div>
<div class="single"><h2>Description</h2>
<div>The main action of this routine is to generate the documentation of the given package and install the Macaulay2 package and documentation. <p>The actual file loaded is <tt>PACKAGENAME.m2</tt>, which should be on the load <a href="_path.html" title="list of directories to look in">path</a> and should contain a package named <tt>PACKAGENAME</tt>.</p>
<p>In order to accomplish this, several steps are performed (or bypassed, depending on the values of the optional arguments).</p>
<ul><li>load the package, if not already loaded (see <a href="_load__Package.html" title="load a package">loadPackage</a>)</li>
<li>determine which help pages have changed since last install</li>
<li>run any new or previously failed examples, or all examples, as specified by the <tt>RemakeAllExamples</tt> (missing documentation<!-- tag: RemakeAllExamples -->) option</li>
<li>generate the html pages of modified help pages, or all html pages, as specificed by the <a href="___Remake__All__Documentation.html" title="name for an optional argument">RemakeAllDocumentation</a> option</li>
<li>generate the info pages, or not, as specified by the <a href="___Make__Info.html" title="name for an optional argument">MakeInfo</a> option</li>
<li>install the documentation and package in the location specified by the <a href="___Package__Prefix.html" title="name for an optional argument">PackagePrefix</a> option</li>
<li>create symbolic links in the location specified by the <a href="___Install__Prefix.html" title="name for an optional argument">InstallPrefix</a> option</li>
<li>place a link to this html documentation in the file <tt>index.html</tt> in the user's <a href="_application__Directory.html" title="the path to the user's application directory">application directory</a>; see <a href="_make__Package__Index.html" title="">makePackageIndex</a></li>
</ul>
<p>The current value of <a href="_prefix__Path.html" title="absolute locations of Macaulay2 files">prefixPath</a> is used to determine how to direct documentation hyperlinks, provided the value of the option <a href="___Absolute__Links.html" title="name for an optional argument">AbsoluteLinks</a> is <a href="_true.html" title="">true</a>, as it is by default; the link will be directed to the appropriate file if one is found by searching the trees referred to by <a href="_prefix__Path.html" title="absolute locations of Macaulay2 files">prefixPath</a>. Otherwise, all documentation hyperlinks are relative to positions within a single tree of directories, as describe by <a href="_current__Layout.html" title="relative locations of Macaulay2 files">Layout</a>.</p>
<p>It might be necessary to run <a href="_install__Package.html" title="load and install a package and its documentation ">installPackage</a> twice if a package with the same name is already installed: the second installation will redirect the hyperlinks to the freshly installed documentation, because the files will have been installed by the first installation. This applies, for example, to those authors who are developing updates to packages already included with Macaulay2.</p>
<p>The files of the package are placed in subdirectories of the appropriate prefix directory as specified by <a href="_current__Layout.html" title="relative locations of Macaulay2 files">Layout</a>, depending on the value of the <a href="___Separate__Exec.html" title="name for an optional argument">SeparateExec</a> option: when it is false the files are all in <tt>share/Macaulay2/PACKAGENAME.m2</tt>, <tt>share/info/PACKAGENAME.info</tt>, <tt>lib/Macaulay2/i686-Linux-Fedora-15/PACKAGENAME/</tt>, <tt>share/Macaulay2/PACKAGENAME/</tt>, and <tt>share/doc/Macaulay2/PACKAGENAME/</tt>; when it is true the paths to the files are modified to reflect the type of your machine, e.g., <tt>common/share/Macaulay2/PACKAGENAME.m2</tt>, <tt>common/share/info/PACKAGENAME.info</tt>, <tt>common/lib/Macaulay2/i686-Linux-Fedora-15/PACKAGENAME/</tt>, <tt>common/share/Macaulay2/PACKAGENAME/</tt>, and <tt>common/share/doc/Macaulay2/PACKAGENAME/</tt>.</p>
<p>In addition, if no errors occurred during running the examples, then an empty file whose name is <tt>lib/Macaulay2/i686-Linux-Fedora-15/PACKAGENAME/.installed</tt> or <tt>common/lib/Macaulay2/i686-Linux-Fedora-15/PACKAGENAME/.installed</tt> is created, to signify that installation was completed.</p>
</div>
</div>
<div class="single"><h2>See also</h2>
<ul><li><span><a href="_packages.html" title="">packages</a></span></li>
<li><span><a href="_epkg.html" title="">epkg</a></span></li>
<li><span><a href="_prefix__Path.html" title="absolute locations of Macaulay2 files">prefixPath</a> -- absolute locations of Macaulay2 files</span></li>
<li><span><a href="_current__Layout.html" title="relative locations of Macaulay2 files">Layout</a> -- relative locations of Macaulay2 files</span></li>
</ul>
</div>
<div class="waystouse"><h2>Ways to use <tt>installPackage</tt> :</h2>
<ul><li>installPackage(Package)</li>
<li>installPackage(String)</li>
</ul>
</div>
</div>
</body>
</html>
