Ticket #12016: trac_12016-sage.v2.patch

File trac_12016-sage.v2.patch, 24.8 KB (added by jhpalmieri, 11 years ago)

  • doc/en/developer/doctesting.rst 

    # HG changeset patch
# User J. H. Palmieri <palmieri@math.washington.edu>
# Date 1321130698 28800
# Node ID 36ba7d92845214da7ef4c0554a85d409537cb352
# Parent  8d81fcf27e1444bfa3778c5fe2cc231c7f84d50a
#12016: document make ptestlong -- how to set NUM_THREADS

diff --git a/doc/en/developer/doctesting.rst b/doc/en/developer/doctesting.rst
    a b its documentation. Testing can be perfor 
    99multiple threads. After compiling a source version of Sage, doctesting
    1010can be run on the whole Sage library, on all modules under a given
    1111directory, or on a specified module only. For the purposes of this
    12 chapter, suppose we have compiled Sage 4.1.1 from source and the top
     12chapter, suppose we have compiled Sage 4.8 from source and the top
    1313level Sage directory is
    1414
    1515::
    1616
    17     [mvngu@sage sage-4.1.1]$ pwd
    18     /scratch/mvngu/build/sage-4.1.1
     17    [mvngu@sage sage-4.8]$ pwd
     18    /scratch/mvngu/build/sage-4.8
    1919
    2020See the section :ref:`chapter-testing` for information on Sage's
    2121automated testing process. The general syntax for doctesting is as
    2222follows. To doctest a module in the library of a version of Sage, use
    2323this syntax::
    2424
    25     /path/to/sage-x.y.z/sage -t [-long] /path/to/sage-x.y.z/path/to/module.py[x]
     25    /path/to/sage-x.y.z/sage -t [--long] /path/to/sage-x.y.z/path/to/module.py[x]
    2626
    2727where ``-long`` is an optional argument. The version of ``sage`` used must
    2828match the version of Sage containing the module we want to doctest. A
    … … Say we want to run all tests in the sudo 
    3939top level Sage directory of our local Sage installation. Now  we can
    4040start doctesting as demonstrated in the following terminal session::
    4141
    42     [mvngu@sage sage-4.1.1]$ ./sage -t devel/sage-main/sage/games/sudoku.py
     42    [mvngu@sage sage-4.8]$ ./sage -t devel/sage-main/sage/games/sudoku.py
    4343    sage -t  "devel/sage-main/sage/games/sudoku.py"
    4444             [6.0 s]
    4545
    … … takes about six seconds, while testing a 
    5252same amount of time. In this case, we only tested one module so it is
    5353not surprising that the total testing time is approximately the same
    5454as the time required to test only that one module. Notice that the
    55 syntax is
     55syntax is ::
    5656
    57 ::
    58 
    59     [mvngu@sage sage-4.1.1]$ ./sage -t devel/sage-main/sage/games/sudoku.py
     57    [mvngu@sage sage-4.8]$ ./sage -t devel/sage-main/sage/games/sudoku.py
    6058    sage -t  "devel/sage-main/sage/games/sudoku.py"
    6159             [5.7 s]
    6260
    6361    ----------------------------------------------------------------------
    6462    All tests passed!
    6563    Total time for all tests: 5.7 seconds
    66     [mvngu@sage sage-4.1.1]$ ./sage -t "devel/sage-main/sage/games/sudoku.py"
     64    [mvngu@sage sage-4.8]$ ./sage -t "devel/sage-main/sage/games/sudoku.py"
    6765    sage -t  "devel/sage-main/sage/games/sudoku.py"
    6866             [5.4 s]
    6967
    … … syntax is 
    7169    All tests passed!
    7270    Total time for all tests: 5.4 seconds
    7371
    74 but not
     72but not ::
    7573
    76 ::
    77 
    78     [mvngu@sage sage-4.1.1]$ ./sage -t sage/games/sudoku.py
     74    [mvngu@sage sage-4.8]$ ./sage -t sage/games/sudoku.py
    7975    ERROR: File ./sage/games/sudoku.py is missing
    8076    exit code: 1
    8177
    … … but not 
    8480
    8581    ./sage/games/sudoku.py
    8682    Total time for all tests: 0.0 seconds
    87     [mvngu@sage sage-4.1.1]$ ./sage -t "sage/games/sudoku.py"
     83    [mvngu@sage sage-4.8]$ ./sage -t "sage/games/sudoku.py"
    8884    ERROR: File ./sage/games/sudoku.py is missing
    8985    exit code: 1
    9086
    … … but not 
    9793We can also first ``cd`` to the directory containing the module
    9894``sudoku.py`` and doctest that module as follows::
    9995
    100     [mvngu@sage sage-4.1.1]$ cd devel/sage-main/sage/games/
     96    [mvngu@sage sage-4.8]$ cd devel/sage-main/sage/games/
    10197    [mvngu@sage games]$ ls
    102     all.py    __init__.py         sudoku_backtrack.pyx
    103     hexad.py  sudoku_backtrack.c  sudoku.py
     98    __init__.py  hexad.py       sudoku.py           sudoku_backtrack.pyx
     99    all.py       quantumino.py  sudoku_backtrack.c
    104100    [mvngu@sage games]$ ../../../../sage -t sudoku.py
    105101    sage -t  "devel/sage-main/sage/games/sudoku.py"
    106102             [5.1 s]
    … … our system has multiple Sage installatio 
    128124syntax is acceptable because we explicitly specify the Sage
    129125installation in the current ``SAGE_ROOT``::
    130126
    131     [mvngu@sage sage-4.1.1]$ ./sage -t devel/sage-main/sage/games/sudoku.py
     127    [mvngu@sage sage-4.8]$ ./sage -t devel/sage-main/sage/games/sudoku.py
    132128    sage -t  "devel/sage-main/sage/games/sudoku.py"
    133129             [5.1 s]
    134130
    135131    ----------------------------------------------------------------------
    136132    All tests passed!
    137133    Total time for all tests: 5.1 seconds
    138     [mvngu@sage sage-4.1.1]$ ./sage -t "devel/sage-main/sage/games/sudoku.py"
     134    [mvngu@sage sage-4.8]$ ./sage -t "devel/sage-main/sage/games/sudoku.py"
    139135    sage -t  "devel/sage-main/sage/games/sudoku.py"
    140136            [5.0 s]
    141137
    … … installation in the current ``SAGE_ROOT` 
    143139    All tests passed!
    144140    Total time for all tests: 5.0 seconds
    145141
    146 With a regular user account, the following syntax is not recommended
    147 as we are using a system-wide Sage installation (if it exists)::
     142The following syntax is not recommended as we are using a system-wide
     143Sage installation (if it exists)::
    148144
    149     [mvngu@sage sage-4.1.1]$ sage -t devel/sage-main/sage/games/sudoku.py
     145    [mvngu@sage sage-4.8]$ sage -t devel/sage-main/sage/games/sudoku.py
    150146    Traceback (most recent call last):
    151147      File "/usr/local/sage/local/bin/sage-test", line 49, in
    152148        os.makedirs(TMP)
    153149      File "/usr/local/sage/local/lib/python/os.py", line 157, in makedirs
    154150        mkdir(name, mode)
    155151    OSError: [Errno 13] Permission denied: '/usr/local/sage/tmp/tmp'
    156     [mvngu@sage sage-4.1.1]$ sage -t "devel/sage-main/sage/games/sudoku.py"
     152    [mvngu@sage sage-4.8]$ sage -t "devel/sage-main/sage/games/sudoku.py"
    157153    Traceback (most recent call last):
    158154      File "/usr/local/sage/local/bin/sage-test", line 49, in
    159155        os.makedirs(TMP)
    … … regular user, we cannot write to directo 
    171167write permission. The following syntax is also discouraged when we
    172168login as a regular user::
    173169
    174     [mvngu@sage sage-4.1.1]$ cd
     170    [mvngu@sage sage-4.8]$ cd
    175171    [mvngu@sage ~]$ sage -t devel/sage-main/sage/games/sudoku.py
    176172    Traceback (most recent call last):
    177173      File "/usr/local/sage/local/bin/sage-test", line 49, in
    … … there. As a regular user, we do not usua 
    195191the directory ``/root`` nor do we have privileges to write to the root
    196192directory::
    197193
    198     [mvngu@sage sage-4.1.1]$ ls /root/
     194    [mvngu@sage sage-4.8]$ ls /root/
    199195    ls: cannot open directory /root/: Permission denied
    200     [mvngu@sage sage-4.1.1]$ cd /
     196    [mvngu@sage sage-4.8]$ cd /
    201197    [mvngu@sage /]$ touch demo.txt
    202198    touch: cannot touch `demo.txt': Permission denied
    203199
    … … and then using two threads. For this exa 
    219215all the modules under ``sage/crypto/``. We can use a syntax similar to
    220216that shown above to achieve this::
    221217
    222     [mvngu@sage sage-4.1.1]$ ./sage -t devel/sage-main/sage/crypto/
     218    [mvngu@sage sage-4.8]$ ./sage -t devel/sage-main/sage/crypto/
    223219    sage -t  "devel/sage-main/sage/crypto/lfsr.py"
    224220             [2.5 s]
    225221    sage -t  "devel/sage-main/sage/crypto/cryptosystem.py"
    … … that shown above to achieve this:: 
    260256    Total time for all tests: 35.7 seconds
    261257
    262258Now we do the same thing, but this time we also use the optional
    263 argument ``-long``::
     259argument ``--long``::
    264260
    265     [mvngu@sage sage-4.1.1]$ ./sage -t -long devel/sage-main/sage/crypto/
    266     sage -t -long "devel/sage-main/sage/crypto/lfsr.py"
     261    [mvngu@sage sage-4.8]$ ./sage -t --long devel/sage-main/sage/crypto/
     262    sage -t --long "devel/sage-main/sage/crypto/lfsr.py"
    267263                  [1.9 s]
    268     sage -t -long "devel/sage-main/sage/crypto/cryptosystem.py"
     264    sage -t --long "devel/sage-main/sage/crypto/cryptosystem.py"
    269265                  [2.0 s]
    270     sage -t -long "devel/sage-main/sage/crypto/block_cipher/miniaes.py"
     266    sage -t --long "devel/sage-main/sage/crypto/block_cipher/miniaes.py"
    271267                  [2.6 s]
    272     sage -t -long "devel/sage-main/sage/crypto/block_cipher/all.py"
     268    sage -t --long "devel/sage-main/sage/crypto/block_cipher/all.py"
    273269                  [0.1 s]
    274     sage -t -long "devel/sage-main/sage/crypto/block_cipher/__init__.py"
     270    sage -t --long "devel/sage-main/sage/crypto/block_cipher/__init__.py"
    275271                  [0.1 s]
    276     sage -t -long "devel/sage-main/sage/crypto/classical.py"
     272    sage -t --long "devel/sage-main/sage/crypto/classical.py"
    277273                  [2.7 s]
    278     sage -t -long "devel/sage-main/sage/crypto/mq/mpolynomialsystem.py"
     274    sage -t --long "devel/sage-main/sage/crypto/mq/mpolynomialsystem.py"
    279275                  [8.7 s]
    280     sage -t -long "devel/sage-main/sage/crypto/mq/mpolynomialsystemgenerator.py"
     276    sage -t --long "devel/sage-main/sage/crypto/mq/mpolynomialsystemgenerator.py"
    281277                  [2.2 s]
    282     sage -t -long "devel/sage-main/sage/crypto/mq/__init__.py"
     278    sage -t --long "devel/sage-main/sage/crypto/mq/__init__.py"
    283279                  [0.1 s]
    284     sage -t -long "devel/sage-main/sage/crypto/mq/sbox.py"
     280    sage -t --long "devel/sage-main/sage/crypto/mq/sbox.py"
    285281                  [2.9 s]
    286     sage -t -long "devel/sage-main/sage/crypto/mq/sr.py"
     282    sage -t --long "devel/sage-main/sage/crypto/mq/sr.py"
    287283                  [56.6 s]
    288     sage -t -long "devel/sage-main/sage/crypto/stream_cipher.py"
     284    sage -t --long "devel/sage-main/sage/crypto/stream_cipher.py"
    289285                  [2.5 s]
    290     sage -t -long "devel/sage-main/sage/crypto/all.py"
     286    sage -t --long "devel/sage-main/sage/crypto/all.py"
    291287                  [0.1 s]
    292     sage -t -long "devel/sage-main/sage/crypto/stream.py"
     288    sage -t --long "devel/sage-main/sage/crypto/stream.py"
    293289                  [1.9 s]
    294     sage -t -long "devel/sage-main/sage/crypto/__init__.py"
     290    sage -t --long "devel/sage-main/sage/crypto/__init__.py"
    295291                  [0.1 s]
    296     sage -t -long "devel/sage-main/sage/crypto/classical_cipher.py"
     292    sage -t --long "devel/sage-main/sage/crypto/classical_cipher.py"
    297293                  [1.9 s]
    298     sage -t -long "devel/sage-main/sage/crypto/cipher.py"
     294    sage -t --long "devel/sage-main/sage/crypto/cipher.py"
    299295                  [1.9 s]
    300296
    301297    ----------------------------------------------------------------------
    … … argument ``-long``:: 
    303299    Total time for all tests: 88.0 seconds
    304300
    305301Notice the time difference between the first set of tests and the
    306 second set, which uses the optional argument ``-long``. Many tests in the
     302second set, which uses the optional argument ``--long``. Many tests in the
    307303Sage library are flagged with ``# long time`` because these are known to
    308 take a long time to run through. Without using the optional ``-long``
     304take a long time to run through. Without using the optional ``--long``
    309305argument, the module ``sage/crypto/mq/sr.py`` took about five
    310306seconds. With this optional argument, it required 57 seconds to run
    311307through all tests in that module. Here is a snippet of a function in
    … … as taking a long time:: 
    315311    def test_consistency(max_n=2, **kwargs):
    316312        r"""
    317313        Test all combinations of ``r``, ``c``, ``e`` and ``n`` in ``(1,
    318         2)`` for consistency of random encryptions and their polynomial
    319         systems. `\GF{2}` and `\GF{2^e}` systems are tested. This test
    320         takes
     314        2)`` for consistency of random encryptions and their polynomial
     315        systems. `\GF{2}` and `\GF{2^e}` systems are tested. This test takes
    321316        a while.
    322317
    323318        INPUT:
    … … as taking a long time:: 
    328323        TESTS::
    329324
    330325            sage: from sage.crypto.mq.sr import test_consistency
    331             sage: test_consistency(1) # long time -- calling w/ max_n = 2 requires a LOT of RAM (>> 2GB, evidently).  Calling w/ max_n = 1 is far more manageable.
     326            sage: test_consistency(1) # long time (80s on sage.math, 2011)
    332327            True
    333 
    334         The above doctest used to fail on a machine with "only" 2GB RAM.
    335         Using ``max_n = 1`` appears to be a more reasonable memory usage.
    336328        """
    337329
    338 Now we doctest the same directory in parallel using two threads::
     330Now we doctest the same directory in parallel using four threads::
    339331
    340     [mvngu@sage sage-4.1.1]$ ./sage -tp 2 devel/sage-main/sage/crypto/
     332    [mvngu@sage sage-4.8]$ ./sage -tp 4 devel/sage-main/sage/crypto/
    341333    Global iterations: 1
    342334    File iterations: 1
    343335    Using cached timings to run longest doctests first.
    344     Doctesting 17 files doing 2 jobs in parallel
     336    Doctesting 17 files doing 4 jobs in parallel
    345337    sage -t  devel/sage-main/sage/crypto/lfsr.py
    346338             [2.7 s]
    347339    sage -t  devel/sage-main/sage/crypto/cryptosystem.py
    … … Now we doctest the same directory in par 
    382374    Timings have been updated.
    383375    Total time for all tests: 19.3 seconds
    384376
    385     [mvngu@sage sage-4.1.1]$ ./sage -tp 2 -long devel/sage-main/sage/crypto/
     377    [mvngu@sage sage-4.8]$ ./sage -tp 4 --long devel/sage-main/sage/crypto/
    386378    Global iterations: 1
    387379    File iterations: 1
    388380    No long cached timings exist; will create upon successful finish.
    389     Doctesting 17 files doing 2 jobs in parallel
    390     sage -t -long devel/sage-main/sage/crypto/cryptosystem.py
     381    Doctesting 17 files doing 4 jobs in parallel
     382    sage -t --long devel/sage-main/sage/crypto/cryptosystem.py
    391383             [2.7 s]
    392     sage -t -long devel/sage-main/sage/crypto/lfsr.py
     384    sage -t --long devel/sage-main/sage/crypto/lfsr.py
    393385             [2.7 s]
    394     sage -t -long devel/sage-main/sage/crypto/stream_cipher.py
     386    sage -t --long devel/sage-main/sage/crypto/stream_cipher.py
    395387             [2.2 s]
    396     sage -t -long devel/sage-main/sage/crypto/all.py
     388    sage -t --long devel/sage-main/sage/crypto/all.py
    397389             [0.1 s]
    398     sage -t -long devel/sage-main/sage/crypto/classical.py
     390    sage -t --long devel/sage-main/sage/crypto/classical.py
    399391             [3.0 s]
    400     sage -t -long devel/sage-main/sage/crypto/__init__.py
     392    sage -t --long devel/sage-main/sage/crypto/__init__.py
    401393             [0.1 s]
    402     sage -t -long devel/sage-main/sage/crypto/stream.py
     394    sage -t --long devel/sage-main/sage/crypto/stream.py
    403395             [2.1 s]
    404     sage -t -long devel/sage-main/sage/crypto/classical_cipher.py
     396    sage -t --long devel/sage-main/sage/crypto/classical_cipher.py
    405397             [2.1 s]
    406     sage -t -long devel/sage-main/sage/crypto/cipher.py
     398    sage -t --long devel/sage-main/sage/crypto/cipher.py
    407399             [2.1 s]
    408     sage -t -long devel/sage-main/sage/crypto/block_cipher/all.py
     400    sage -t --long devel/sage-main/sage/crypto/block_cipher/all.py
    409401             [0.1 s]
    410     sage -t -long devel/sage-main/sage/crypto/block_cipher/__init__.py
     402    sage -t --long devel/sage-main/sage/crypto/block_cipher/__init__.py
    411403             [0.1 s]
    412     sage -t -long devel/sage-main/sage/crypto/block_cipher/miniaes.py
     404    sage -t --long devel/sage-main/sage/crypto/block_cipher/miniaes.py
    413405             [2.8 s]
    414     sage -t -long devel/sage-main/sage/crypto/mq/mpolynomialsystemgenerator.py
     406    sage -t --long devel/sage-main/sage/crypto/mq/mpolynomialsystemgenerator.py
    415407             [2.0 s]
    416     sage -t -long devel/sage-main/sage/crypto/mq/__init__.py
     408    sage -t --long devel/sage-main/sage/crypto/mq/__init__.py
    417409             [0.1 s]
    418     sage -t -long devel/sage-main/sage/crypto/mq/sbox.py
     410    sage -t --long devel/sage-main/sage/crypto/mq/sbox.py
    419411             [3.1 s]
    420     sage -t -long devel/sage-main/sage/crypto/mq/mpolynomialsystem.py
     412    sage -t --long devel/sage-main/sage/crypto/mq/mpolynomialsystem.py
    421413             [9.1 s]
    422     sage -t -long devel/sage-main/sage/crypto/mq/sr.py
     414    sage -t --long devel/sage-main/sage/crypto/mq/sr.py
    423415             [56.0 s]
    424416
    425417    ----------------------------------------------------------------------
    … … Parallel testing the whole Sage library 
    443435The main Sage library resides in the directory
    444436``SAGE_ROOT/devel/sage-main/``. We can use the syntax described above
    445437to doctest the main library using multiple threads. When doing release
    446 management or patching the main Sage library, a release manager would
    447 parallel test the library using ten or more threads::
     438management or patching the main Sage library, a release manager might
     439parallel test the library using ten threads with the following
     440command::
    448441
    449     [mvngu@sage sage-4.1.1]$ ./sage -tp 10 -long devel/sage-main/
     442    [mvngu@sage sage-4.8]$ ./sage -tp 10 --long devel/sage-main/
    450443
    451 Another way is to edit the file ``Makefile`` in the top level Sage
    452 directory so that the variable ``NUM_THREADS`` is set to ``10``::
     444Another way is to run ``make ptestlong``, which builds Sage (if
     445necessary), builds the Sage documentation (if necessary), and then
     446runs parallel doctests.  By default, this determines the number of
     447threads by reading the environment variable :envvar:`MAKE`: if it is
     448set to ``make -j12``, then use 12 threads.  If :envvar:`MAKE` is not
     449set, then it uses ``min(8, cpu_count())``, where ``cpu_count()`` is
     450the number of CPUs in the machine, as determined by the Python
     451function ``multiprocessing.cpu_count()``.  The number of threads can be
     452overridden by setting the environment variable
     453:envvar:`SAGE_NUM_THREADS`.
    453454
    454     # How many threads should be used when doing parallel testing (and
    455     # sometime in the future, parallel building)?
    456     NUM_THREADS=10
     455In any case, this will test the Sage library with multiple threads::
    457456
    458 After saving all changes to ``Makefile``, we can parallel test with the
    459 ``-long`` option using ten threads::
    460 
    461     [mvngu@sage sage-4.1.1]$ make ptestlong
     457    [mvngu@sage sage-4.8]$ make ptestlong
    462458
    463459Any of the following commands would also doctest the Sage library or
    464460one of its clones::
    … … by the symbolic link ``devel/sage``. 
    497493
    498494* ``make ptest`` --- Similar to the commands ``make test`` and ``make
    499495  check``. However, doctesting is run with the number of threads as
    500   specified by the variable ``NUM_THREADS``. See the file
    501   ``SAGE_ROOT/Makefile`` for further details.
     496  described above for ``make ptestlong``.
    502497
    503498* ``make ptestlong`` --- Similar to the command ``make ptest``, but
    504499  using the optional argument ``-long`` for doctesting.
    … … by the symbolic link ``devel/sage``. 
    507502Beyond the Sage library
    508503=======================
    509504
    510 The doctesting scripts of a Sage installation currently have limited
    511 support for doctesting of modules outside of the Sage library for
    512 that version of Sage. We cannot use the doctesting scripts of Sage
    513 4.1.1 to doctest modules in, say, Sage 4.1. Doing so would result
    514 in errors::
    515 
    516     [mvngu@sage sage-4.1.1]$ ./sage -t ../sage-4.1/devel/sage-main/sage/games/sudoku.py
    517     sage -t  "../sage-4.1/devel/sage-main/sage/games/sudoku.py"
    518       File "./sudoku.py", line 18
    519         from ../sage-4.1/devel/sage-main/sage/games/sudoku import *
    520                ^
    521     SyntaxError: invalid syntax
    522 
    523              [0.2 s]
    524     exit code: 1024
    525 
    526     ----------------------------------------------------------------------
    527     The following tests failed:
    528 
    529 
    530            sage -t  "../sage-4.1/devel/sage-main/sage/games/sudoku.py"
    531     Total time for all tests: 0.2 seconds
    532 
    533 However, suppose we have a Python script called ``my_python_script.py``
    534 that uses the Sage library. Our Python script has the following
    535 content::
     505Doctesting also works fine for files not in the Sage library.  For
     506example, suppose we have a Python script called
     507``my_python_script.py``::
    536508
    537509    [mvngu@sage build]$ cat my_python_script.py
    538510    from sage.all_cmdline import *   # import sage library
    539511
    540512    def square(n):
    541513        """
    542         Return the square of n.
     514        Return the square of n.
    543515
    544         EXAMPLES::
     516        EXAMPLES::
    545517
    546518            sage: square(2)
    547519            4
    548520        """
    549521        return n**2
    550522
    551 We can use any version of Sage to doctest our Python script, so long
    552 as that version of Sage has features that are used in our script. For
    553 example, we can use both Sage 4.1.1 and 4.1 to doctest the above
    554 Python script::
     523Then we can doctest it just as with Sage library files::
    555524
    556     [mvngu@sage build]$ sage-4.1/sage -t my_python_script.py
     525    [mvngu@sage build]$ sage-4.8/sage -t my_python_script.py
    557526    sage -t  "my_python_script.py"
    558527             [1.3 s]
    559528
    560529    ----------------------------------------------------------------------
    561530    All tests passed!
    562531    Total time for all tests: 1.3 seconds
    563     [mvngu@sage build]$ sage-4.1.1/sage -t my_python_script.py
    564     sage -t  "my_python_script.py"
    565              [1.4 s]
    566 
    567     ----------------------------------------------------------------------
    568     All tests passed!
    569     Total time for all tests: 1.4 seconds
    570 
    571 Doctesting can also be performed on Sage scripts. Say we have a Sage
    572 script called ``my_sage_script.sage`` with the following content::
    573 
    574     [mvngu@sage build]$ cat my_sage_script.sage
    575     def cube(n):
    576         r"""
    577         Return the cube of n.
    578 
    579         EXAMPLES::
    580 
    581             sage: cube(2)
    582             8
    583         """
    584         return n**3
    585 
    586 This must be converted to an equivalent Python script prior to
    587 doctesting. First, we use Sage to convert ``my_sage_script.sage`` to
    588 an equivalent Python script called ``my_sage_script.py``::
    589 
    590     [mvngu@sage build]$ sage-4.1.1/sage my_sage_script.sage
    591     [mvngu@sage build]$ cat my_sage_script.py
    592     # This file was *autogenerated* from the file my_sage_script.sage.
    593     from sage.all_cmdline import *   # import sage library
    594     _sage_const_3 = Integer(3)
    595     def cube(n):
    596         r"""
    597         Return the cube of n.
    598 
    599         EXAMPLES::
    600 
    601             sage: cube(2)
    602             8
    603         """
    604         return n**_sage_const_3
    605 
    606 Doctesting is then performed on that equivalent Python script::
    607 
    608     [mvngu@sage build]$ sage-4.1.1/sage -t my_sage_script.py
    609     sage -t  "my_sage_script.py"
    610              [1.5 s]
    611 
    612     ----------------------------------------------------------------------
    613     All tests passed!
    614     Total time for all tests: 1.5 seconds

  • doc/en/installation/source.rst 

    diff --git a/doc/en/installation/source.rst b/doc/en/installation/source.rst
    a b process: 
    588588  time.  Alternatively, run "make build-serial" which sets this
    589589  environment variable for you.
    590590
     591- :envvar:`SAGE_NUM_THREADS` - if this is set to a number, then when
     592  building the documentation, parallel doctesting, or running ``sage
     593  -b``, use this many threads.  If it is set to ``0``, then use as
     594  many threads as seems sensible.  If it is set to ``auto``, then
     595  build the documentation serially, but parallel test or run ``sage
     596  -b`` using as many threads as seems sensible.  If this is not set,
     597  then determine the number of threads using the value of the
     598  :envvar:`MAKE` variable, as above.
     599
    591600- :envvar:`SAGE_CHECK` - if this is set to "yes", then during the
    592601  build process, run the test suite for each package which has one.
    593602

  • setup.py 

    diff --git a/setup.py b/setup.py
    a b def execute_list_of_commands(command_lis 
    292292    OUTPUT:
    293293        For each entry in command_list, we attempt to run the command.
    294294        If it is a string, we call os.system. If it is a pair [f, v],
    295         we call f(v). On machines with more than 1 cpu the commands
    296         are run in parallel.
     295        we call f(v).  If the '-j' flag in 'MAKE' is set, run in parallel.
    297296    """
    298297    t = time.time()
    299     cpu_count = number_of_threads()  # try hard to determine the actual cpu count
    300     assert(cpu_count>=1)
    301     nthreads = 0  # number of threads to use; zero means don't know
    302 
    303     if os.environ.has_key('MAKE'):  # user-supplied number of threads takes precedence
    304         MAKE = os.environ['MAKE']
    305         # from the manpage: If there is more than one -j option, the last one is effective.
    306         pos = MAKE.rfind(' -j')
    307         if pos>=0:
    308             try:
    309                 if MAKE[pos+3] == '=':   # make -j=N is the same as make -jN
    310                     pos += 1
    311                 nthreads = int(MAKE[pos+3:].split()[0])
    312             except IndexError, ValueError:
    313                 # make -j without number means unlimited threads
    314                 nthreads = 2*cpu_count
    315 
    316     if nthreads==0:
    317         nthreads = cpu_count
    318 
    319     if nthreads > 2*cpu_count:  # sanity check
    320         print "Warning: The number of threads ("+str(nthreads)+") seems impossibly large."
    321         nthreads = min(nthreads, cpu_count)
    322         print "I reduced it to "+str(nthreads)+"."
     298    # Determine the number of threads from the environment variable
     299    # SAGE_NUM_THREADS, which is set automatically by the script
     300    # sage-env, using the setting of the variable MAKE.
     301    NUM_THREADS = os.environ.get('SAGE_NUM_THREADS', 1)
     302    try:
     303        nthreads = int(NUM_THREADS)
     304    except ValueError:
     305        # NUM_THREADS might be 'auto', in which case use the number of
     306        # cpus.
     307        nthreads = 0
     308    # If SAGE_NUM_THREADS is 0, use the number of cpus.
     309    if nthreads == 0:
     310        nthreads = number_of_threads()
     311        assert(nthreads >= 1)
    323312
    324313    # normalize the command_list to handle strings correctly
    325314    command_list = [ [run_command, x] if isinstance(x, str) else x for x in command_list ]