Macaulay2 » Documentation
Packages » Macaulay2Doc » The Macaulay2 language » creating a package » newPackage
next | previous | forward | backward | up | index | toc

# newPackage -- the preamble of a package

- Usage:
    `newPackage ( PackageName, ... )`
- Inputs:
  - PackageName, a string, the name of the new package
- Optional inputs:
  - Version => a string, 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 => a string, default value null, the date of this version of the package
  - InfoDirSection => a string, 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 => a string, 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 => a string, default value null, the URI pointing to the home page of the package, if any
  - DebuggingMode => a Boolean value, default value false, whether debuggingMode should be true during package loading. However, if debuggingMode is already false, it will remain so.
  - AuxiliaryFiles => a Boolean value, 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 => a Boolean value, 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 => a Boolean value, 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 => a Boolean value, 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 => a Boolean value, default value false, whether to reload the package, if it has been loaded before
- Outputs:
  - a package, 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 => {}
            )

## See also

- packages -- Macaulay2 packages
- creating a package
- readPackage -- read the package preamble
- loadPackage -- load a package
- needsPackage -- load a package if not already loaded

## Ways to use newPackage:

- `newPackage(String)`

## For the programmer

The object newPackage is a method function with a single argument.

The source of this document is in /build/macaulay2-88fgJW/macaulay2-1.25.11+ds/M2/Macaulay2/packages/Macaulay2Doc/functions/package-doc.m2:688:0.