-
Notifications
You must be signed in to change notification settings - Fork 1
Package creation tutorial
Daniel R. Grayson edited this page Sep 17, 2019
·
1 revision
On Monday Grayson gave a brief overview of package writing, with this transcript:
Macaulay2, version 1.14
--loading configuration for package "FourTiTwo" from file /Users/dan/Library/Application Support/Macaulay2/init-FourTiTwo.m2
--loading configuration for package "Topcom" from file /Users/dan/Library/Application Support/Macaulay2/init-Topcom.m2
with packages: ConwayPolynomials, Elimination, IntegralClosure, InverseSystems, LLLBases, PrimaryDecomposition, ReesAlgebra,
TangentCone, Truncations
i1 :
Process M2 finished
+ M2 --no-readline --print-width 100
Macaulay2, version 1.14
--loading configuration for package "FourTiTwo" from file /Users/dan/Library/Application Support/Macaulay2/init-FourTiTwo.m2
--loading configuration for package "Topcom" from file /Users/dan/Library/Application Support/Macaulay2/init-Topcom.m2
with packages: ConwayPolynomials, Elimination, IntegralClosure, InverseSystems, LLLBases,
PrimaryDecomposition, ReesAlgebra, TangentCone, Truncations
i1 : 1..100
o1 = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
-----------------------------------------------------------------------------------------------
27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50,
-----------------------------------------------------------------------------------------------
51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74,
-----------------------------------------------------------------------------------------------
75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98,
-----------------------------------------------------------------------------------------------
99, 100)
o1 : Sequence
i2 : asdfsdf
o2 = asdfsdf
o2 : Symbol
i3 : dictionaryPath
o3 = {Truncations.Dictionary, SimpleDoc.Dictionary, InverseSystems.Dictionary,
-----------------------------------------------------------------------------------------------
ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary, TangentCone.Dictionary,
-----------------------------------------------------------------------------------------------
Classic.Dictionary, PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,
-----------------------------------------------------------------------------------------------
LLLBases.Dictionary, Elimination.Dictionary, User#"private dictionary", User.Dictionary,
-----------------------------------------------------------------------------------------------
Core.Dictionary, OutputDictionary, PackageDictionary}
o3 : List
i4 : keys IntegralClosure.Dictionary
o4 = {IntegralClosure$ringFromFractions, IntegralClosure$AllCodimensions, IntegralClosure$icMap,
-----------------------------------------------------------------------------------------------
IntegralClosure$conductor, IntegralClosure$icFracP, IntegralClosure$Verbosity,
-----------------------------------------------------------------------------------------------
ringFromFractions, IntegralClosure$integralClosures, AllCodimensions,
-----------------------------------------------------------------------------------------------
IntegralClosure$RadicalCodim1, IntegralClosure$Keep, IntegralClosure$integralClosure,
-----------------------------------------------------------------------------------------------
IntegralClosure$Index, IntegralClosure$idealizer, IntegralClosure$makeS2, icMap,
-----------------------------------------------------------------------------------------------
IntegralClosure$icFractions, integralClosures, Keep, IntegralClosure$isNormal, conductor,
-----------------------------------------------------------------------------------------------
icFracP, IntegralClosure$ConductorElement, Verbosity, makeS2, RadicalCodim1, integralClosure,
-----------------------------------------------------------------------------------------------
isNormal, Index, idealizer, IntegralClosure$icPIdeal, ConductorElement, icFractions, icPIdeal}
o4 : List
i5 : loadPackage "Foo"
o5 = Foo
o5 : Package
i6 : loadPackage "Foo"
Foo.m2:1:1:(3):[7]: error: package Foo not reloaded; try Reload => true
Foo.m2:1:1:(3):[7]: --entering debugger (type help to see debugger commands)
Foo.m2:1:1-1:1: --source code:
newPackage "Foo"
ii7 : loadPackage ("Foo", Reload => true)
oo7 = Foo
oo7 : Package
ii8 : foo
oo8 = foo
oo8 : Symbol
ii9 : dictionaryPath
oo9 = {Foo.Dictionary, Truncations.Dictionary, SimpleDoc.Dictionary, InverseSystems.Dictionary,
----------------------------------------------------------------------------------------------
ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary, TangentCone.Dictionary,
----------------------------------------------------------------------------------------------
Classic.Dictionary, PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,
----------------------------------------------------------------------------------------------
LLLBases.Dictionary, Elimination.Dictionary, User#"private dictionary", User.Dictionary,
----------------------------------------------------------------------------------------------
Core.Dictionary, OutputDictionary, PackageDictionary}
oo9 : List
ii10 : keys Foo.Dictionary
oo10 = {}
oo10 : List
ii11 : loadPackage ("Foo", Reload => true)
oo11 = Foo
oo11 : Package
ii12 : keys Foo.Dictionary
oo12 = {Foo$foo, foo}
oo12 : List
ii13 : foo
oo13 = foo
oo13 : FunctionClosure
ii14 : foo 7
oo14 = 8
ii15 : loadPackage ("Foo", Reload => true)
oo15 = Foo
oo15 : Package
ii16 : foo 7
oo16 = 6
ii17 : bar
oo17 = bar
oo17 : Symbol
ii18 : loadPackage ("Foo", Reload => true)
oo18 = Foo
oo18 : Package
ii19 : keys Foo.Dictionary
oo19 = {Foo$foo, bar, Foo$bar, foo}
oo19 : List
ii20 : Foo$foo
oo20 = foo
oo20 : FunctionClosure
ii21 : loadPackage ("Foo", Reload => true)
oo21 = Foo
oo21 : Package
ii22 : sin
oo22 = sin
oo22 : FunctionClosure
ii23 : sin .4
oo23 = .8
oo23 : RR (of precision 53)
ii24 : restart
Macaulay2, version 1.14
--loading configuration for package "FourTiTwo" from file /Users/dan/Library/Application Support/Macaulay2/init-FourTiTwo.m2
--loading configuration for package "Topcom" from file /Users/dan/Library/Application Support/Macaulay2/init-Topcom.m2
with packages: ConwayPolynomials, Elimination, IntegralClosure, InverseSystems, LLLBases,
PrimaryDecomposition, ReesAlgebra, TangentCone, Truncations
i1 : loadPackage ("Foo", Reload => true)
--warning: symbol "sin" in Core.Dictionary is shadowed by a symbol in Foo.Dictionary
-- use the synonym Core$sin
o1 = Foo
o1 : Package
i2 : dictionaryPath
o2 = {Foo.Dictionary, Truncations.Dictionary, SimpleDoc.Dictionary, InverseSystems.Dictionary,
-----------------------------------------------------------------------------------------------
ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary, TangentCone.Dictionary,
-----------------------------------------------------------------------------------------------
Classic.Dictionary, PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,
-----------------------------------------------------------------------------------------------
LLLBases.Dictionary, Elimination.Dictionary, User#"private dictionary", User.Dictionary,
-----------------------------------------------------------------------------------------------
Core.Dictionary, OutputDictionary, PackageDictionary}
o2 : List
i3 : Core$sin .4
o3 = .389418342308651
o3 : RR (of precision 53)
i4 : help newPackage
o4 = newPackage
**********
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 : 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 |
| OptionalComponentsPresent => true |
| PackageExports => {} |
| PackageImports => {} |
| Reload => false |
| UseCachedExampleOutput => false |
| Version => 1.1 |
| |
|o3 : OptionTable |
+--------------------------------------------------------------+
|i4 : oo.Headline |
| |
|o4 = making Foo |
+--------------------------------------------------------------+
|i5 : (options Core).Version |
| |
|o5 = 1.14 |
+--------------------------------------------------------------+
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 => {}
)
Ways to use newPackage :
========================
* "newPackage(String)" -- package item: start a new package
o4 : DIV
i5 : loadPackage ("Foo", Reload => true)
Foo.m2:1:1:(3):[7]: error: newPackage: expected Version option of class String
Foo.m2:1:1:(3):[7]: --entering debugger (type help to see debugger commands)
Foo.m2:1:1-9:22: --source code:
newPackage("Foo",
Headline => "compute foos",
Version => 1.0,
Date => "September 16, 2019",
Authors => {
{Name => "Dan", Email => "drg", HomePage => "dangrayson.com"}
},
DebuggingMode => false
)
ii6 :
i7 : loadPackage ("Foo", Reload => true)
--warning: symbol "sin" in Core.Dictionary is shadowed by a symbol in Foo.Dictionary
-- use the synonym Core$sin
o7 = Foo
o7 : Package
i8 : viewHelp SimpleDoc
i9 : print packageTemplate "Foo"
i10 : loadPackage ("Foo", Reload => true)
Foo.m2:18:1:(2):[7]: error: line 4 of string: expected single indented line after Headline
i11 : loadPackage ("Foo", Reload => true)
Foo.m2:18:1:(2):[7]: error: empty list of examples encountered
i12 : loadPackage ("Foo", Reload => true)
--warning: symbol "sin" in Core.Dictionary is shadowed by a symbol in Foo.Dictionary
-- use the synonym Core$sin
o12 = Foo
o12 : Package
i13 : help Foo
--warning: tag has no documentation: Foo :: bar, key "bar", package null
--warning: tag has no documentation: Foo :: foo, key "foo", package null
o13 = Foo -- compute foos
*******************
Description
===========
Here we compute foo of 8.
+-----+
|foo 8|
+-----+
Caveat
======
Version
=======
This documentation describes version 0.1 of Foo.
Source code
===========
The source code from which this documentation is derived is in the file Foo.m2 (see
share/Macaulay2/Foo.m2 ).
Exports
=======
* Functions and commands
* "bar"
* "foo"
* "sin" -- compute the sine
o13 : DIV
i14 : installPackage "Foo"
--warning: symbol "sin" in Core.Dictionary is shadowed by a symbol in Foo.Dictionary
-- use the synonym Core$sin
--installing package Foo in /Users/dan/Library/Application Support/Macaulay2/local/ with layout 1
--using package sources found in /Users/dan/
--storing raw documentation in /Users/dan/Library/Application Support/Macaulay2/local/lib/Macaulay2/Foo/cache/rawdocumentation-dcba-8.db
--closed the database
--running tests that are functions
--making example result files in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/example-output/
--making example results for Foo in file /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/example-output/___Foo.out
ulimit -c unlimited; ulimit -t 700; ulimit -m 850000; ulimit -v 850000; ulimit -s 8192; ulimit -n 512; cd /var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/1-rundir/; GC_MAXIMUM_HEAP_SIZE=400M /Applications/Macaulay2-1.14/bin/M2-binary --silent --print-width 77 --stop --int --no-readline --no-randomize -e 'needsPackage("Foo", Reload => true, FileName => "/Users/dan/Foo.m2")' <"/var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/0___Foo.m2" >>"/Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/example-output/___Foo.errors" 2>&1
--processing documentation nodes...
--assembling table of contents
--warning: symbol has no documentation: Foo :: bar, package Foo
--warning: symbol has no documentation: Foo :: sin, package Foo
--warning: symbol has no documentation: Foo :: foo, package Foo
--warning: 3 warning(s) occurred in documentation for package Foo
--making info file in /Users/dan/Library/Application Support/Macaulay2/local/share/info/Foo.info.tmp
--completed info file moved to /Users/dan/Library/Application Support/Macaulay2/local/share/info/Foo.info
--making empty html pages in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/html/
--making html pages in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/html/
--making 'Foo : Index' in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/html/master.html
--making Foo : Table of Contents' in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/html/toc.html
--file created: /Users/dan/Library/Application Support/Macaulay2/local/lib/Macaulay2/Foo/.installed
--installed package Foo in /Users/dan/Library/Application Support/Macaulay2/local/
i15 : viewHelp Foo
stdio:14:1:(3): error: package Foo is not installed on the prefixPath
i16 : restart
Macaulay2, version 1.14
--loading configuration for package "FourTiTwo" from file /Users/dan/Library/Application Support/Macaulay2/init-FourTiTwo.m2
--loading configuration for package "Topcom" from file /Users/dan/Library/Application Support/Macaulay2/init-Topcom.m2
with packages: ConwayPolynomials, Elimination, IntegralClosure, InverseSystems, LLLBases,
PrimaryDecomposition, ReesAlgebra, TangentCone, Truncations
i1 : loadPackage ("Foo", Reload => true)
--warning: symbol "sin" in Core.Dictionary is shadowed by a symbol in Foo.Dictionary
-- use the synonym Core$sin
o1 = Foo
o1 : Package
i2 : viewHelp Foo
i3 : foo 8
o3 = 7
i4 : installPackage "Foo"
--warning: symbol "sin" in Core.Dictionary is shadowed by a symbol in Foo.Dictionary
-- use the synonym Core$sin
--installing package Foo in /Users/dan/Library/Application Support/Macaulay2/local/ with layout 1
--using package sources found in /Users/dan/
--storing raw documentation in /Users/dan/Library/Application Support/Macaulay2/local/lib/Macaulay2/Foo/cache/rawdocumentation-dcba-8.db
--closed the database
--running tests that are functions
--making example result files in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/example-output/
--processing documentation nodes...
--assembling table of contents
--warning: symbol has no documentation: Foo :: bar, package Foo
--warning: symbol has no documentation: Foo :: sin, package Foo
--warning: symbol has no documentation: Foo :: foo, package Foo
--warning: 3 warning(s) occurred in documentation for package Foo
--making info file in /Users/dan/Library/Application Support/Macaulay2/local/share/info/Foo.info.tmp
--completed info file moved to /Users/dan/Library/Application Support/Macaulay2/local/share/info/Foo.info
--making empty html pages in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/html/
--making html pages in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/html/
--making 'Foo : Index' in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/html/master.html
--making Foo : Table of Contents' in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Foo/html/toc.html
--file created: /Users/dan/Library/Application Support/Macaulay2/local/lib/Macaulay2/Foo/.installed
--installed package Foo in /Users/dan/Library/Application Support/Macaulay2/local/
i5 : check Foo
--running test 0 of package Foo on line 36 in file ./Foo.m2
-- rerun with: check_0 "Foo"
--making test results in file /var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/1.out
ulimit -c unlimited; ulimit -t 700; ulimit -m 850000; ulimit -v 850000; ulimit -s 8192; ulimit -n 512; cd /var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/2-rundir/; GC_MAXIMUM_HEAP_SIZE=400M /Applications/Macaulay2-1.14/bin/M2-binary --silent --print-width 77 --stop --int --no-readline --no-randomize -e 'needsPackage("Foo", Reload => true, FileName => "/Users/dan/Foo.m2")' <"/var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/1.m2" >>"/var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/1.tmp" 2>&1
i6 : loadPackage ("Foo", Reload => true)
--warning: symbol "sin" in Core.Dictionary is shadowed by a symbol in Foo.Dictionary
-- use the synonym Core$sin
o6 = Foo
o6 : Package
i7 : check Foo
--running test 0 of package Foo on line 36 in file ./Foo.m2
-- rerun with: check_0 "Foo"
--making test results in file /var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/3.out
ulimit -c unlimited; ulimit -t 700; ulimit -m 850000; ulimit -v 850000; ulimit -s 8192; ulimit -n 512; cd /var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/4-rundir/; GC_MAXIMUM_HEAP_SIZE=400M /Applications/Macaulay2-1.14/bin/M2-binary --silent --print-width 77 --stop --int --no-readline --no-randomize -e 'needsPackage("Foo", Reload => true, FileName => "/Users/dan/Foo.m2")' <"/var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/3.m2" >>"/var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/3.tmp" 2>&1
/var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/3.tmp:0:1: (output file) error: Macaulay2 exited with status code 1
/var/folders/46/9b86vqxj4hjcngvy7kd7sb140000gn/T/M2-25507-0/3.m2:0:1: (input file)
M2: *** Error 1
stdio:7:1:(3): error: 1 error(s) occurred running tests for package Foo
i8 :
Process M2 finished