<?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>newPackage(String) -- package item: start a new package</title>
<link rel="stylesheet" type="text/css" href="../../../../Macaulay2/Style/doc.css"/>
</head>
<body>
<table class="buttons">
<tr>
<td><div><a href="_export.html">next</a> | <a href="_an_spexample_spof_spa_sppackage.html">previous</a> | <a href="_export.html">forward</a> | <a href="_an_spexample_spof_spa_sppackage.html">backward</a> | <a href="_creating_spa_sppackage.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="_creating_spa_sppackage.html" title="">creating a package</a> > <a href="_new__Package_lp__String_rp.html" title="package item: start a new package">newPackage(String)</a></div>
<hr/>
<div><h1>newPackage(String) -- package item: start a new package</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>newPackage ( title )</tt></div>
</dd></dl>
</div>
</li>
<li><span>Function: <a href="_new__Package_lp__String_rp.html" title="package item: start a new package">newPackage</a></span></li>
<li><div class="single">Inputs:<ul><li><span><tt>title</tt>, <span>a <a href="___String.html">string</a></span>, the name of the new package</span></li>
</ul>
</div>
</li>
<li><div class="single">Consequences:<ul><li>a package is created</li>
</ul>
</div>
</li>
<li><div class="single"><a href="_using_spfunctions_spwith_spoptional_spinputs.html">Optional inputs</a>:<ul><li><span><tt>Version => </tt><span><span>a <a href="___String.html">string</a></span>, <span>default value 0.0</span>, the version number of the package. A version number less than 1.0 indicates that the package is under development, and the user interface may change.</span></span></li>
<li><span><tt>Date => </tt><span><span>a <a href="___String.html">string</a></span>, <span>default value null</span>, the date of this version of the package</span></span></li>
<li><span><tt>InfoDirSection => </tt><span><span>a <a href="___String.html">string</a></span>, <span>default value Macaulay2 and its packages</span>, the title of the section in the info page directory where the menu entry for this package should be made</span></span></li>
<li><span><tt>Headline => </tt><span><span>a <a href="___String.html">string</a></span>, <span>default value null</span>, a brief (5-10 words) description of the package</span></span></li>
<li><span><tt>Authors => </tt><span><span>a <a href="___List.html">list</a></span>, <span>default value {}</span>, a list of lists of options, one for each author. The suboptions are of the form <tt>Name => x</tt>, <tt>Email => x</tt>, or <tt>HomePage => x</tt>, where <tt>x</tt> is a string.</span></span></li>
<li><span><tt>HomePage => </tt><span><span>a <a href="___String.html">string</a></span>, <span>default value null</span>, the URI pointing to the home page of the package, if any</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 <a href="_debugging__Mode.html" title="whether to enter the debugger when an error occurs">debuggingMode</a> should be true during package loading</span></span></li>
<li><span><tt>AuxiliaryFiles => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value false</span>, whether the package source to be distributed includes a directory for auxiliary files, with the same name as the package</span></span></li>
<li><span><tt>CacheExampleOutput => </tt><span><span>a <a href="___Boolean.html">Boolean value</a></span>, <span>default value null</span>, whether <a href="_install__Package.html" title="load and install a package and its documentation ">installPackage</a> should 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 can be overridden by a value explicitly specified when <a href="_install__Package.html" title="load and install a package and its documentation ">installPackage</a> is called. After the directory is created, it will necessary for the user also to specify <tt>AuxiliaryFiles=>true</tt>.</span></span></li>
<li><span><tt>Certification => </tt><span><span>a <a href="___List.html">list</a></span>, <span>default value null</span>, the certification block inserted by the maintainers of <em>Macaulay2</em> after the package has been accepted for publication by a journal, such as The Journal of Software for Algebra and Geometry: <em>Macaulay2</em>. Authors should not undertake to create such a certification block themselves.</span></span></li>
<li><span><tt>Configuration => </tt><span><span>a <a href="___List.html">list</a></span>, <span>default value {}</span>, a list of configuration options for the package. The keys and values should be constant expressions, such as strings and integers, not incorporating symbols to be exported by the package (and not yet defined). The first time the package is loaded by the user, unless the <tt>-q</tt> option is specified on the <tt>M2</tt> command line, these options will be stored in a file in the user's application directory (see <a href="_application__Directory.html" title="the path to the user's application directory">applicationDirectory</a>). The user can change the configuration by editing the file. The user can override the configuration settings when loading the package; see <a href="_load__Package.html" title="load a package">loadPackage(..., Configuration => ...)</a> and <a href="_needs__Package.html" title="load a package if not already loaded">needsPackage(..., Configuration => ...)</a>. The file will be overwritten when a newer version of the package with different configuration options is loaded, but a backup will be made and the user's settings for the surviving options will be retained. </span></span></li>
</ul>
</div>
</li>
</ul>
</div>
<div class="single"><h2>Description</h2>
<div><p>The dictionaries for the symbols in the packages loaded by the user are moved out of the way to avoid conflicts, so just the standard pre-loaded packages are visible to the source code of the package. In addition, the package <a href="../../SimpleDoc/html/index.html">SimpleDoc</a> is made available. If functions from additional packages are needed by the code in the new package, then <a href="_needs__Package.html" title="load a package if not already loaded">needsPackage</a> can be used (after the use of <a href="_new__Package_lp__String_rp.html" title="package item: start a new package">newPackage</a>) to provide them. If functions from additional packages are needed by the user who will load the new package, then <a href="_needs__Package.html" title="load a package if not already loaded">needsPackage</a> can be used (before the use of <a href="_new__Package_lp__String_rp.html" title="package item: start a new package">newPackage</a>) to provide them.</p>
<table class="examples"><tr><td><pre>i1 : newPackage("Foo",
Version => "1.1",
Headline => "making Foo",
Configuration => { "foo" => 42, "bar" => "x" }
)
o1 = Foo
o1 : Package</pre>
</td></tr>
<tr><td><pre>i2 : endPackage "Foo"
o2 = Foo
o2 : Package</pre>
</td></tr>
</table>
The options can be recovered with <a href="_options.html" title="get options">options</a> as follows.<table class="examples"><tr><td><pre>i3 : options Foo
o3 = OptionTable{Authors => {} }
AuxiliaryFiles => false
CacheExampleOutput => null
Certification => null
Configuration => {foo => 42, bar => x}
Date => null
DebuggingMode => false
Headline => making Foo
HomePage => null
InfoDirSection => Macaulay2 and its packages
Version => 1.1
o3 : OptionTable</pre>
</td></tr>
<tr><td><pre>i4 : oo.Headline
o4 = making Foo</pre>
</td></tr>
<tr><td><pre>i5 : (options Core).Version
o5 = 1.3.1</pre>
</td></tr>
</table>
<p>Here is a template for a typical <tt>newPackage</tt> entry in a package.</p>
<pre>newPackage("PACKAGENAME",
Headline => "one line description",
Version => 0.1,
Date => "month XX, 20XX",
Authors => {
{Name => "author1", Email => "email1", HomePage => "url1"}
{Name => "author2", Email => "email2", HomePage => "url2"},
},
DebuggingMode => true,
HomePage => "http://univ.edu/~user/PACKAGENAME/",
Configuration => {}
)</pre>
</div>
</div>
<div class="single"><h2>See also</h2>
<ul><li><span><a href="_packages.html" title="">packages</a></span></li>
</ul>
</div>
</div>
</body>
</html>
