# newPackage -- the preamble of a package

## Synopsis

• Usage:
newPackage ( PackageName, ... )
• Inputs:
• PackageName, , the name of the new package
• Optional inputs:
• Version => , default value 0.0, 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.
• Date => , default value null, the date of this version of the package
• InfoDirSection => , default value Macaulay2 and its packages, the title of the section in the info page directory where the menu entry for this package should be made
• Headline => , default value null, a brief (5-10 words) description of the package
• Authors => a list, default value {}, each entry is a list of options the form Name => x, Email => x, or HomePage => x, where x is a string.
• Keywords => a list, default value {Uncategorized}, the entries are keywords describing the package, used to classify the package in the list of packages provided with Macaulay2
• HomePage => , default value null, the URI pointing to the home page of the package, if any
• DebuggingMode => , default value false, whether debuggingMode should be true during package loading. However, if debuggingMode is already false, it will remain so.
• AuxiliaryFiles => , default value false, whether the package source to be distributed includes a directory for auxiliary files, with the same name as the package
• PackageExports => a list, default value {}, the entries are names of other packages to load, both for the user and for the code of the new package
• PackageImports => a list, default value {}, the entries of names of other packages to load, just for the code of the new package
• CacheExampleOutput => , default value null, whether installPackage should cache (newer) example output in a subdirectory of the auxiliary file directory named examples, for use in a future installation. This value can be overridden by a value explicitly specified when installPackage is called. After the directory is created, it will necessary for the user also to specify AuxiliaryFiles => true.
• OptionalComponentsPresent => , default value null, whether all optional external components of the package are present on the system. Unless the user sets this option or CacheExampleOutput to true, this option will be initialized to true.
• UseCachedExampleOutput => , default value null, whether installPackage should copy previously cached example output, if it is present and corresponds to the current example input for a node, rather than rerunning the examples, which might be important if optional external software is not present in the system. This is relevant only when CacheExampleOutput and AuxiliaryFiles are set to true. Unless set by the user, it is set to the negation of the value of OptionalComponentsPresent.
• Certification => a list, default value null, the certification block inserted by the maintainers of Macaulay2 after the package has been accepted for publication by a journal, such as The Journal of Software for Algebra and Geometry: Macaulay2. Authors should not undertake to create such a certification block themselves.
• Configuration => a list, default value {}, the entries are 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 -q option is specified on the M2 command line, these options will be stored in a file in the user's application directory (see applicationDirectory). The user can change the configuration by editing the file. The user can override the configuration settings when loading the package; see loadPackage(...,Configuration=>...) and needsPackage(...,Configuration=>...). 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.
• Reload => , default value false, whether to reload the package, if it has been loaded before
• Outputs:
• , the new package
• Consequences:
• a package is created

## Description

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 SimpleDoc is made available. If functions from additional packages are needed by the code in the new package, then needsPackage can be used (after the use of newPackage) to provide them. If functions from additional packages are needed by the user who will load the new package, then needsPackage can be used (before the use of newPackage) to provide them.

 i1 : newPackage("Foo", Version => "1.1", Headline => "making Foo", Configuration => { "foo" => 42, "bar" => "x" } ) o1 = Foo o1 : Package i2 : endPackage "Foo" o2 = Foo o2 : Package

The options can be recovered with options as follows.

 i3 : opts = 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 Keywords => {Uncategorized} OptionalComponentsPresent => true PackageExports => {} PackageImports => {} Reload => false UseCachedExampleOutput => false Version => 1.1 o3 : OptionTable i4 : opts.Headline o4 = making Foo

Here is a template for a typical newPackage entry in a package.

 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 => false, HomePage => "http://univ.edu/~user/PackageName/", Configuration => {} )