#16048: dev docs: Inclusion Procedure for New and Updated Packages
-------------------------------------+-------------------------------------
Reporter: rws | Owner:
Type: defect | Status: needs_work
Priority: major | Milestone: sage-6.2
Component: documentation | Resolution:
Keywords: | Merged in:
Authors: Ralf Stephan | Reviewers: R. Andrew Ohanar,
Report Upstream: N/A | Jeroen Demeyer, Vincent Delecroix
Branch: public/spkg- | Work issues:
devdoc-1 | Commit:
Dependencies: | 42e05b1e7a1655e8c7b29712340e922029be05ba
| Stopgaps:
-------------------------------------+-------------------------------------
Changes (by vdelecroix):
* status: needs_review => needs_work
Comment:
I am very sorry to be very picky but I definitely think that the
documentation is an important piece of a software. Please for each of my
comment, say explicitly if you agree or not (you did it for my 1) before
but you mostly eluded the other two). I am happy to make the changes you
accept by myself if you prefer.
'''section "Inclusion Procedure for New and Updated Packages"'''
As it is the case in all other sections, it would be nice if you add a
line break after the title.
For the politics about tickets, I thought that:
- experimental = does not build on all platforms officially supported =>
never be optional
- optional = does build on all platforms => can possibly become standard
after some time
The sentence "In short, packages consist of a link to the original tarball
with additional
code under !``SAGE_ROOT/build/pkgs!``" is not meaningful at this stage of
the document. It is not clear what is a "package" nor what is an "original
tarball". I would simply remove the sentence as this section is purely
about "how do you submit" and not "how do you make your own package".
Moreover, I would would better put this section near the end of the
document because before submitting a package you need to build one ;-).
'''section "Directory structure"'''
In the sentence "to package it in Sage" you must uppercase the "t". At the
very same place I suggest to put a comment in parenthesis "... distribute
a tarball !``foo-1.3.tar.gz!`` (that will be automatically placed in
!``SAGE_ROOT/upstream!`` during the installation process)" or something
similar.
'''section "Manual package build and installation"'''
I think that the shell command
{{{
$ SAGE_CHECK=yes sage -f package_name
}}}
will not do what you expect. You might either put a column between the
{{{SAGE_CHECK=yes}}} and the {{{sage -f package_name}}} or put it in two
lines.
There are at least 5 important missing things:
- {{{sage -i PACKAGE_NAME}}} is the standard command to install a package
- if a package is already installed, we can perform the tests only with
{{{sage -i -c PACKAGE_NAME}}} (what the {{{-c}}} option does is that it
set {{{SAGE_CHECK}}} to yes + some extra mystery about
SAGE_CHECK_PACKAGES)
- to force the reinstallation of a package we can do {{{sage -i -f
PACKAGE_NAME}}} (and {{{sage -f PACKAGE_NAME}}} is a shortcut for it)
- the install script is in $SAGE_ROOT/local/bin/install (and Sage
reinvented the wheel here!!). It is relatively well documented and is
worth to points its existence.
--
Ticket URL: <http://trac.sagemath.org/ticket/16048#comment:14>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
