[sagemath] 01/01: Re-org and add more documentation
Ximin Luo
infinity0 at debian.org
Sun Dec 4 12:41:58 UTC 2016
This is an automated email from the git hooks/post-receive script.
infinity0 pushed a commit to branch master
in repository sagemath.
commit 4e1a03ec52e344d83b549c92fc49c9821fad3206
Author: Ximin Luo <infinity0 at debian.org>
Date: Sun Dec 4 13:41:49 2016 +0100
Re-org and add more documentation
---
debian/README.Debian | 152 ++++++--------------------------
debian/{README.Debian => README.source} | 151 +++++++++++++++++--------------
debian/{todo-stretch.md => TODO} | 0
3 files changed, 114 insertions(+), 189 deletions(-)
diff --git a/debian/README.Debian b/debian/README.Debian
index 30199f4..75d04dc 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -1,143 +1,45 @@
-#Building Sage against Debian libraries:
+==================
+SageMath in Debian
+==================
-See https://wiki.debian.org/DebianScience/Sage
-for instructions on using this repository.
+Disabled features
+=================
-It's recommended that you build with "DEB_BUILD_PROFILES=pkg.sagemath.ccache".
-This uses debian/ccache as a ccache cache, so rebuilds are much quicker.
+Some features of SageMath in Debian are currently disabled for various reasons.
+These are summarised below; see the respective packages for more details.
-## TODO (required for the build to work)
+jmol, jmol-applet: JSmol is completely unavailable, because it does not satisfy
+the Debian Free Software Guidelines. It may be possible to resolve this, see
+the package documentation for details. Help is needed!
-No local system changes should be needed at this time for the main and dochtml
-builds to work automatically from a clean check-out.
+python-sagenb: SageNB HTTPS unsupported, because certtool is not yet in Debian.
-## TODO (required to get into Debian archives)
+Running doctests
+================
-See todo-stretch.md and https://wiki.debian.org/DebianScience/Sage
-
-## Debugging test failures
-
-The tests write logging output to sage/logs/ptestlong.log or some other file if
-you ran a different test. If you let the test run to completion, near the end
-of the logging output, there will be a summary of all the failures.
-
-After a successful build, you can run individual tests as follows. First, make
-sure you're in the top-level package directory, where debian/ is. Then:
-
- $ export SAGE_LOCAL=$PWD/debian/build/usr
- $ export PYTHONPATH=$SAGE_LOCAL/lib/python2.7/dist-packages
- $ cd sage
- sage$ ./sage -t --long src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py
-
-If doing this after `dh_auto_install` has succeeded (this is the case if you
-got some resulting .debs), then you'll need to change debian/build to
-debian/tmp in the above commands, or symlink the latter to the former.
-
-One can also run the tests using the installed sage packages. First, make sure
-that Debian patches are applied to your sage source directory - this initially
-won't be the case if `dpkg-buildpackage` succeeded. Then, from any directory:
+One can run the tests using the installed sage packages. First, get the source
+code for this package (`apt-get source sagemath`), and make sure the Debian
+patches are applied. Then, from any directory:
*$ export -n SAGE_LOCAL SAGE_ROOT
- *$ SAGE_SRC=/path/to/sage/src sage -t -p --all --long --logfile=ptestlong.log
+ *$ SAGE_SRC=/path/to/sage/src sage -tp --long --logfile=ptestlong.log --all
See https://www.sagemath.org/git-developer-guide/doctesting.html for more
information and helpful tips.
-In particular, always focus on the *first failure* in a single test file; in
-many cases, subsequent failures (such as NameErrors) are due to the first
-failure and many of those will go away after fixing the first one.
-
-The following might be useful:
-
- $ debian/rules EXTRA_SAGE_TEST_FLAGS=-f ptestlong
-
-It will run all previously-failed tests again, which is useful if you're on a
-mass test-fixing spree and forget to count which ones you've fixed. However
-this assumes that you didn't break any of the previously successful ones :p
-
- $ debian/rules failed-tests-by-count
- $ debian/rules failed-tests-by-error
- $ debian/rules failed-tests-by-cause
-
-These, and other related rules, will print you some nice stats about the test
-failures. This is useful if you have say, hundreds or thousands of failures to
-deal with and don't know where to begin.
-
-## Current test status
-
-You should get something roughly like the following. If you get different
-results, please add your experience to the below summary.
-
-First, patch your local system:
-
-# fix 2 tests
-sudo sed -e '/^class AppliedUndef/,${/def _sage_/,/^\s*$/d}' \
- -i /usr/lib/python2.7/dist-packages/sympy/core/function.py
-
-These are already fixed in Debian's git repo for sympy; we're just waiting for
-an upload.
-
-You can see infinity0's test failures here: https://people.debian.org/~infinity0/res/
-Look for files named "sagemath-*_*.log"
-
-Now for the summary:
-
-### Breakdown
-
-25 for infinity0
-?? for Tobias
-
-plus ~2 unreproducible
-
-### Needs further investigation
-
-5 Unknown
-sage -t --long src/sage/interfaces/r.py # 2 doctests failed
-sage -t --long src/sage/rings/number_field/number_field.py # 3 doctests failed
-
-3 arctan2(0,0) gives NaN instead of Error
-sage -t --long src/sage/functions/trig.py # 1 doctest failed
-sage -t --long src/sage/symbolic/expression.pyx # 1 doctest failed
-sage -t --long src/sage/symbolic/expression_conversions.py # 1 doctest failed
-
-### Have a good idea on how to proceed
-
-5 Minor floating point differences, can maybe ignore, ask upstream first
-sage -t --long src/sage/coding/code_bounds.py # 1 doctest failed
-sage -t --long src/sage/numerical/optimize.py # 4 doctests failed (1 not floating-point related, see below)
-sage -t --long src/sage/functions/exp_integral.py # 1 doctest failed
-
-6 Can probably ignore / fix trivially
-sage -t --long src/sage/interfaces/tests.py # 2 doctests failed
-sage -t --long src/sage/graphs/strongly_regular_db.pyx # 1 doctest failed
-sage -t --long src/sage/rings/integer.pyx # 1 doctest failed
-sage -t --long src/sage/homology/simplicial_complex.py # 1 doctest failed (see upstream #15585)
-sage -t --long src/sage/geometry/polyhedron/backend_cdd.py # 1 doctest failed
-
-3 Others, known
-sage -t --long src/sage/libs/singular/function.pyx # 2 doctests failed (see upstream #17254#comment:252)
-sage -t --long src/sage/numerical/optimize.py # 4 doctests failed (1 reported as Debian #840159, 3 accounted for above as floating-point related)
-
-### Can't reproduce
-
-Fails first time, but seems to work when you run them a second time, e.g. with
-`debian/rules EXTRA_SAGE_TEST_FLAGS=-f build` or by running `./sage -t` directly
-
-2 Sometimes fails first time
-sage -t --long src/sage/libs/gap/all_documented_functions.py # 1 doctest failed
-sage -t --long src/sage/libs/gap/assigned_names.py # 1 doctest failed
-
-## Manual testing
-
-First, edit /usr/bin/dh_sphinxdoc as shown here:
+Feel free to upload your test logs somewhere and send links to them to our
+mailing list <debian-science-sagemath at lists.alioth.debian.org>. Please do not
+send your test logs directly, unless they are small (<400KB). Compressing them
+would be a good idea, if that helps to bring the size down.
-https://anonscm.debian.org/cgit/python-modules/packages/sphinx.git/commit/?id=7b1c7a8aacf50e7b5aaa23203de8481d6123d459
+If you wish to help debug and fix test failures, see debian/README.source in
+the source package for more guidance on how to do that. In particular, you will
+need to build the source from scratch first.
-Then:
+Known issues
+============
-If you override the failed tests with DEB_BUILD_OPTIONS=nocheck you can build
-some .debs, install them, and test the CLI or the notebooks manually. At the
-moment, quite a lot of stuff is not working:
+At the moment, quite a lot of stuff is not working:
- Sage #21732: '?' doesn't work, e.g.:
diff --git a/debian/README.Debian b/debian/README.source
similarity index 52%
copy from debian/README.Debian
copy to debian/README.source
index 30199f4..b29bd18 100644
--- a/debian/README.Debian
+++ b/debian/README.source
@@ -1,25 +1,36 @@
-#Building Sage against Debian libraries:
+==================
+SageMath in Debian
+==================
-See https://wiki.debian.org/DebianScience/Sage
-for instructions on using this repository.
+Build instructions
+==================
+
+See https://wiki.debian.org/DebianScience/Sage for instructions on setting your
+system up to work with this source package.
It's recommended that you build with "DEB_BUILD_PROFILES=pkg.sagemath.ccache".
This uses debian/ccache as a ccache cache, so rebuilds are much quicker.
-## TODO (required for the build to work)
+Local system patches
+--------------------
No local system changes should be needed at this time for the main and dochtml
builds to work automatically from a clean check-out.
-## TODO (required to get into Debian archives)
+Remaining tasks
+===============
+
+See TODO and https://wiki.debian.org/DebianScience/Sage
-See todo-stretch.md and https://wiki.debian.org/DebianScience/Sage
+Running doctests
+================
-## Debugging test failures
+(These instructions are for running doctests from a built source tree. For
+running doctests from an installed binary package, see README.Debian.)
-The tests write logging output to sage/logs/ptestlong.log or some other file if
-you ran a different test. If you let the test run to completion, near the end
-of the logging output, there will be a summary of all the failures.
+The tests write logging output to sage/logs/ptestlong.log, or some other file
+if you ran a different test. If you let the test run to completion, near the
+end of the logging output, there will be a summary of all the failures.
After a successful build, you can run individual tests as follows. First, make
sure you're in the top-level package directory, where debian/ is. Then:
@@ -27,27 +38,73 @@ sure you're in the top-level package directory, where debian/ is. Then:
$ export SAGE_LOCAL=$PWD/debian/build/usr
$ export PYTHONPATH=$SAGE_LOCAL/lib/python2.7/dist-packages
$ cd sage
- sage$ ./sage -t --long src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py
+ sage$ ./sage -tp --long src/sage/file/you/want/to/test
If doing this after `dh_auto_install` has succeeded (this is the case if you
-got some resulting .debs), then you'll need to change debian/build to
-debian/tmp in the above commands, or symlink the latter to the former.
+got some resulting .debs), then either change debian/build to debian/tmp in the
+above commands, or symlink the latter to the former.
+
+Debugging test failures
+=======================
+
+Always focus on the *first failure* in a given test file. In many cases,
+subsequent failures (such as NameErrors) are due to the first failure, and many
+of those will go away after fixing the first one.
+
+We have some test-analysis rules that will print you some nice stats about the
+failures. For example:
+
+ $ debian/rules failed-tests-by-count
+ $ debian/rules failed-tests-by-error
+ $ debian/rules failed-tests-by-cause
+
+Look in debian/rules for more. These are useful if you have hundreds or
+thousands of failures to deal with and don't know where to begin.
+
+Fixing test failures
+====================
+
+You should get to know the build process (in debian/rules), so that you can
+make fixes to particular test files without having to rebuild everything again,
+which takes ages!
+
+There are three cases:
+
+- Fixing a doctest. That is, something that looks like this:
+
+ [.. sage python/cython code ..]
+ """Some documentation
+
+ sage: (code to be tested)
+ (expected output)
+ """
+ [.. sage python/cython code ..]
+
+ This is the easiest case - simply edit the file in-place in sage/src, then
+ re-run the tests as described above.
-One can also run the tests using the installed sage packages. First, make sure
-that Debian patches are applied to your sage source directory - this initially
-won't be the case if `dpkg-buildpackage` succeeded. Then, from any directory:
+- Fixing python code. That is, code in a .py file that is not a doctest.
- *$ export -n SAGE_LOCAL SAGE_ROOT
- *$ SAGE_SRC=/path/to/sage/src sage -t -p --all --long --logfile=ptestlong.log
+ Edit the file in-place in sage/src/a/b/etc, then copy it over to
+ debian/build/usr/lib/python2.7/dist-packages/a/b/etc (or debian/tmp if
+ `dh_auto_install` had previously succeeded) then run the tests again.
-See https://www.sagemath.org/git-developer-guide/doctesting.html for more
-information and helpful tips.
+- Fixing cython code. That is, code in a .pyx file that is not a doctest.
-In particular, always focus on the *first failure* in a single test file; in
-many cases, subsequent failures (such as NameErrors) are due to the first
-failure and many of those will go away after fixing the first one.
+ You'll need to re-run the build again.
-The following might be useful:
+ First, if debian/tmp/usr exists then move it to debian/build/usr. Then:
+
+ $ DEB_BUILD_OPTIONS=nodoc debian/rules build
+
+ This *should* only build the changed files. However we explicitly avoid
+ rebuilding the documentation, because incremental docbuild is broken
+ currently in upstream (#21612).
+
+ If you are impatient, you can even cancel the build early using Ctrl-C -
+ after it copies .so files into debian/build - then running your test again.
+
+You may also find this useful:
$ debian/rules EXTRA_SAGE_TEST_FLAGS=-f ptestlong
@@ -55,15 +112,14 @@ It will run all previously-failed tests again, which is useful if you're on a
mass test-fixing spree and forget to count which ones you've fixed. However
this assumes that you didn't break any of the previously successful ones :p
- $ debian/rules failed-tests-by-count
- $ debian/rules failed-tests-by-error
- $ debian/rules failed-tests-by-cause
+Finally, after you are satisfied with your fixes, you should do a completely
+clean build to verify these fixes - to make sure that they weren't affected by
+temporary intermediate build products, e.g. due to our short-cuts above.
-These, and other related rules, will print you some nice stats about the test
-failures. This is useful if you have say, hundreds or thousands of failures to
-deal with and don't know where to begin.
+Current test status
+===================
-## Current test status
+(TODO: the below is a bit out of date since November 2016).
You should get something roughly like the following. If you get different
results, please add your experience to the below summary.
@@ -126,36 +182,3 @@ Fails first time, but seems to work when you run them a second time, e.g. with
2 Sometimes fails first time
sage -t --long src/sage/libs/gap/all_documented_functions.py # 1 doctest failed
sage -t --long src/sage/libs/gap/assigned_names.py # 1 doctest failed
-
-## Manual testing
-
-First, edit /usr/bin/dh_sphinxdoc as shown here:
-
-https://anonscm.debian.org/cgit/python-modules/packages/sphinx.git/commit/?id=7b1c7a8aacf50e7b5aaa23203de8481d6123d459
-
-Then:
-
-If you override the failed tests with DEB_BUILD_OPTIONS=nocheck you can build
-some .debs, install them, and test the CLI or the notebooks manually. At the
-moment, quite a lot of stuff is not working:
-
-- Sage #21732: '?' doesn't work, e.g.:
-
-sage: plot?
----------------------------------------------------------------------------
-ImportError Traceback (most recent call last)
-
-[..]
-
-/usr/lib/python2.7/dist-packages/sage/misc/sagedoc.py in process_extlinks(s, embedded)
- 466 oldpath = sys.path
- 467 sys.path = [os.path.join(SAGE_DOC_SRC, 'common')] + oldpath
---> 468 from conf import extlinks
- 469 sys.path = oldpath
- 470 for key in extlinks:
-
-ImportError: No module named conf
-
-- SageNB doesn't load some stuff - see browser console
-
-- Jupyter doesn't load some stuff - see browser console
diff --git a/debian/todo-stretch.md b/debian/TODO
similarity index 100%
rename from debian/todo-stretch.md
rename to debian/TODO
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/sagemath.git
More information about the debian-science-commits
mailing list