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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
==================
SageMath in Debian
==================
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.
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.
Remaining tasks
===============
See TODO and https://wiki.debian.org/DebianScience/Sage
Running doctests
================
(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.
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:
$ . <(debian/rules export-build-env) # assumes you're in bash or zsh
sage$ ./sage -t -p --long src/sage/file/you/want/to/test
See https://www.sagemath.org/git-developer-guide/doctesting.html for more
information and helpful tips.
Rewinding the build
-------------------
For various technical reasons, you might need to do some extra manual steps for
the above and below commands to work.
- To run them after `dh_auto_install` has succeeded, first move or symlink
debian/tmp to debian/build.
- To run them after `dpkg-buildpackage` has succeeded, you'll need to apply all
the debian patches again, then also do the previous point.
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.
- Fixing python code. That is, code in a .py file that is not a doctest.
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.
- Fixing cython code. That is, code in a .pyx file that is not a doctest.
You'll need to re-run the build again. First, make sure you've followed any
applicable commands from the "Rewinding the build" section above. 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 currently
broken 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 run your test again.
You may also find this useful:
$ debian/rules check-failed
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
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.
Current test status
-------------------
You should get something roughly like the following. If you get different
results, please add your experience to the below summary.
You can see infinity0's test failures here: https://people.debian.org/~infinity0/sage/
Look for files named "sagemath-*_*.log"
Known causes::
sage -t --long src/sage/homology/simplicial_complex.py # 1 doctest failed (see upstream #15585)
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 # 1 doctest failed (1 reported as Debian #840159)
We're not sure why the below occur, or if they indicate a major problem. Some
of them involve advanced mathematics, which we're not too familiar with.
Files with "many" failures::
sage -t --long src/sage/coding/linear_code.py # 3 doctests failed
sage -t --long src/sage/misc/randstate.pyx # 13 doctests failed
Files with "few" failures::
sage -t --long src/sage/algebras/group_algebra.py # 2 doctests failed
sage -t --long src/sage/coding/codecan/autgroup_can_label.pyx # 1 doctest failed
sage -t --long src/sage/geometry/polyhedron/backend_cdd.py # 1 doctest failed
sage -t --long src/sage/groups/matrix_gps/matrix_group.py # 1 doctest failed
sage -t --long src/sage/interfaces/r.py # 2 doctests failed
sage -t --long src/sage/rings/number_field/number_field.py # 1 doctest failed
Manual testing
==============
Pre-install jupyter notebook tests
----------------------------------
To test the jupyter notebook without installing anything, first see "rewinding
the build" above". Then:
1. Copy debian/build/usr/share/jupyter/kernels/sagemath to /usr/share/jupyter/kernels/
2. Fix up the .svg symlinks there.
3. Edit /usr/share/jupyter/kernels/sagemath/kernel.json to say "./sage" instead of /usr/bin/sage.
4. `./sage -n jupyter`
Examples
--------
These can be tested from the Sage CLI, SageNB, and the Jupyter Notebook.
Typesetting::
show(integrate(1/(1+x^4), x))
You should get a long expression with arctans, logs, and square roots.
3D plots::
def f(x,y):
return math.sin(y*y+x*x)/math.sqrt(x*x+y*y+.0001)
P = plot3d(f,(-3,3),(-3,3), adaptive=True, color=rainbow(60, 'rgbtuple'), max_bend=.1, max_depth=15)
P.show()
You should get a 3D plot, or a notice about JSmol being unavailable.
|
