newPackage -- the preamble of a package

Synopsis

• 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

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

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

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