diff --git a/build/bin/sage-print-system-package-command b/build/bin/sage-print-system-package-command index c67ccbbc461..054122ab234 100755 --- a/build/bin/sage-print-system-package-command +++ b/build/bin/sage-print-system-package-command @@ -33,8 +33,8 @@ do PROMPT="${1#--prompt=}" ;; --prompt) - PROMPT=' $ ' - CONTINUATION=' ' + PROMPT='$ ' + CONTINUATION=' ' ;; --continuation=*) CONTINUATION="${1#--continuation=}" diff --git a/src/doc/en/developer/coding_in_other.rst b/src/doc/en/developer/coding_in_other.rst index d59886b5391..8816e8443ee 100644 --- a/src/doc/en/developer/coding_in_other.rst +++ b/src/doc/en/developer/coding_in_other.rst @@ -46,7 +46,7 @@ The ``gen`` class is defined in :sage_root:`src/sage/libs/cypari2/gen.pyx`, and this is where we add the method ``matfrobenius``: -.. CODE-BLOCK:: cython +.. code-block:: cython def matfrobenius(self, flag=0): r""" @@ -102,7 +102,7 @@ class where we call the ``matfrobenius()`` method on the PARI object associated to the matrix after doing some sanity checking. Then we convert output from PARI to Sage objects: -.. CODE-BLOCK:: cython +.. code-block:: cython def frobenius_form(self, flag=0, var='x'): """ @@ -171,7 +171,7 @@ For example, suppose we want to make a wrapper for the computation of the Cartan matrix of a simple Lie algebra. The Cartan matrix of `G_2` is available in GAP using the commands: -.. CODE-BLOCK:: gap +.. code-block:: gap gap> L:= SimpleLieAlgebra( "G", 2, Rationals ); @@ -202,7 +202,7 @@ can convert back to sage using the method ``sage`` if it works. .. skip -.. CODE-BLOCK:: python +.. code-block:: python def cartan_matrix(typ, rank): """ @@ -326,7 +326,7 @@ to carry this out. Here is an example on how to use this command in Singular: -.. CODE-BLOCK:: text +.. code-block:: text A Computer Algebra System for Polynomial Computations / version 3-0-0 0< @@ -449,7 +449,7 @@ just that. .. skip -.. CODE-BLOCK:: python +.. code-block:: python def points_parser(string_points, F): """ @@ -509,7 +509,7 @@ ourselves to points of degree one. .. skip -.. CODE-BLOCK:: python +.. code-block:: python def places_on_curve(f, F): """ @@ -593,7 +593,7 @@ Next, we implement the general function (for brevity we omit the docstring, which is the same as above). Note that the ``point_parser`` function is not required: -.. CODE-BLOCK:: python +.. code-block:: python def places_on_curve(f, F): p = F.characteristic() @@ -634,7 +634,7 @@ For example, here is part of the file defines an interface between Sage and Octave, an open source program for doing numerical computations, among other things: -.. CODE-BLOCK:: python +.. code-block:: python import os from expect import Expect, ExpectElement @@ -648,7 +648,7 @@ basic class for interfaces. The third line defines the class ``Octave``; it derives from ``Expect`` as well. After this comes a docstring, which we omit here (see the file for details). Next comes: -.. CODE-BLOCK:: python +.. code-block:: python def __init__(self, script_subdirectory="", logfile=None, server=None, server_tmpdir=None): @@ -666,7 +666,7 @@ docstring, which we omit here (see the file for details). Next comes: This uses the class ``Expect`` to set up the Octave interface: -.. CODE-BLOCK:: python +.. code-block:: python def set(self, var, value): """ @@ -692,7 +692,7 @@ These let users type ``octave.set('x', 3)``, after which ``octave.get('x')`` returns ``' 3'``. Running ``octave.console()`` dumps the user into an Octave interactive shell: -.. CODE-BLOCK:: python +.. code-block:: python def solve_linear_system(self, A, b): """ diff --git a/src/doc/en/developer/coding_in_python.rst b/src/doc/en/developer/coding_in_python.rst index f86ab9a09c3..1b5585d833e 100644 --- a/src/doc/en/developer/coding_in_python.rst +++ b/src/doc/en/developer/coding_in_python.rst @@ -15,9 +15,9 @@ Python language standard Sage follows the time window-based support policy `SPEC 0 — Minimum Supported Dependencies `_ for Python versions. -The current minimum supported Python version can be found in the -``pyproject.toml`` file. Accordingly, only language and library features -available in this version can be used. If a feature is deprecated in a newer +The current minimum supported Python version can be found in the +``pyproject.toml`` file. Accordingly, only language and library features +available in this version can be used. If a feature is deprecated in a newer supported version, it must be ensured that deprecation warnings issued by Python do not lead to failures in doctests. @@ -274,9 +274,11 @@ preparsed version of ``foo.sage`` is created with the name This file was *autogenerated* from the file foo.sage. You can explicitly preparse a file with the ``--preparse`` -command-line option: running :: +command-line option: running - sage --preparse foo.sage +.. code-block:: console + + $ sage --preparse foo.sage creates the file ``foo.sage.py``. diff --git a/src/doc/en/developer/doctesting.rst b/src/doc/en/developer/doctesting.rst index a88bb87e5d1..fa5430123af 100644 --- a/src/doc/en/developer/doctesting.rst +++ b/src/doc/en/developer/doctesting.rst @@ -14,9 +14,11 @@ multiple threads. After compiling a source version of Sage, doctesting can be run on the whole Sage library, on all modules under a given directory, or on a specified module only. For the purposes of this chapter, suppose we have compiled Sage from source and the top -level directory is:: +level directory is - [jdemeyer@localhost sage]$ pwd +.. code-block:: console + + $ pwd /home/jdemeyer/sage See the section :ref:`chapter-testing` for information on Sage's @@ -24,7 +26,7 @@ automated testing process. The general syntax for doctesting is as follows. To doctest a module in the library of a version of Sage, use this syntax: -.. CODE-BLOCK:: text +.. code-block:: text /path/to/sage_root/sage -t [--long] /path/to/sage_root/path/to/module.py[x] @@ -41,9 +43,11 @@ Testing a module Say we want to run all tests in the sudoku module ``sage/games/sudoku.py``. In a terminal window, first we ``cd`` to the top level Sage directory of our local Sage installation. Now we can -start doctesting as demonstrated in the following terminal session:: +start doctesting as demonstrated in the following terminal session + +.. code-block:: console - [jdemeyer@localhost sage]$ ./sage -t src/sage/games/sudoku.py + $ ./sage -t src/sage/games/sudoku.py Running doctests with ID 2012-07-03-03-36-49-d82849c6. Doctesting 1 file. sage -t src/sage/games/sudoku.py @@ -61,9 +65,11 @@ same amount of time; the total time required includes some startup time for the code that runs the tests. In this case, we only tested one module so it is not surprising that the total testing time is approximately the same as the time required to test only that one -module. Notice that the syntax is:: +module. Notice that the syntax is - [jdemeyer@localhost sage]$ ./sage -t src/sage/games/sudoku.py +.. code-block:: console + + $ ./sage -t src/sage/games/sudoku.py Running doctests with ID 2012-07-03-03-39-02-da6accbb. Doctesting 1 file. sage -t src/sage/games/sudoku.py @@ -75,21 +81,25 @@ module. Notice that the syntax is:: cpu time: 3.6 seconds cumulative wall time: 3.6 seconds -but not:: +but not + +.. code-block:: console - [jdemeyer@localhost sage]$ ./sage -t sage/games/sudoku.py + $ ./sage -t sage/games/sudoku.py Running doctests with ID 2012-07-03-03-40-53-6cc4f29f. No files matching sage/games/sudoku.py No files to doctest We can also first ``cd`` to the directory containing the module -``sudoku.py`` and doctest that module as follows:: +``sudoku.py`` and doctest that module as follows - [jdemeyer@localhost sage]$ cd src/sage/games/ - [jdemeyer@localhost games]$ ls +.. code-block:: console + + $ cd src/sage/games/ + $ ls __init__.py hexad.py sudoku.py sudoku_backtrack.pyx all.py quantumino.py sudoku_backtrack.c - [jdemeyer@localhost games]$ ../../../../sage -t sudoku.py + $ ../../../../sage -t sudoku.py Running doctests with ID 2012-07-03-03-41-39-95ebd2ff. Doctesting 1 file. sage -t sudoku.py @@ -106,9 +116,11 @@ Sage to test its own modules. Even if we have a system-wide Sage installation, using that version to doctest the modules of a local installation is a recipe for confusion. -You can also run the Sage doctester as follows:: +You can also run the Sage doctester as follows + +.. code-block:: console - [jdemeyer@localhost sage]$ ./sage -tox -e doctest -- src/sage/games/sudoku.py + $ ./sage -tox -e doctest -- src/sage/games/sudoku.py See :ref:`chapter-tools` for more information about tox. @@ -124,9 +136,11 @@ run tests, we use that particular Sage installation via the syntax ``sage``. This is a precaution against confusion that can arise when our system has multiple Sage installations. For example, the following syntax is acceptable because we explicitly specify the Sage -installation in the current ``SAGE_ROOT``:: +installation in the current ``SAGE_ROOT`` + +.. code-block:: console - [jdemeyer@localhost sage]$ ./sage -t src/sage/games/sudoku.py + $ ./sage -t src/sage/games/sudoku.py Running doctests with ID 2012-07-03-03-43-24-a3449f54. Doctesting 1 file. sage -t src/sage/games/sudoku.py @@ -137,7 +151,7 @@ installation in the current ``SAGE_ROOT``:: Total time for all tests: 4.9 seconds cpu time: 3.6 seconds cumulative wall time: 3.6 seconds - [jdemeyer@localhost sage]$ ./sage -t "src/sage/games/sudoku.py" + $ ./sage -t "src/sage/games/sudoku.py" Running doctests with ID 2012-07-03-03-43-54-ac8ca007. Doctesting 1 file. sage -t src/sage/games/sudoku.py @@ -154,37 +168,37 @@ Sage installation (if it exists): .. skip -:: +.. code-block:: console - [jdemeyer@localhost sage]$ sage -t src/sage/games/sudoku.py + $ sage -t src/sage/games/sudoku.py sage -t "src/sage/games/sudoku.py" ********************************************************************** File "/home/jdemeyer/sage/src/sage/games/sudoku.py", line 515: sage: next(h.solve(algorithm='backtrack')) Exception raised: Traceback (most recent call last): - File "/usr/local/sage/local/bin/ncadoctest.py", line 1231, in run_one_test + File "/usr/local/sage/local/bin/ncadoctest.py", line 1231, in run_one_test self.run_one_example(test, example, filename, compileflags) - File "/usr/local/sage/local/bin/sagedoctest.py", line 38, in run_one_example + File "/usr/local/sage/local/bin/sagedoctest.py", line 38, in run_one_example OrigDocTestRunner.run_one_example(self, test, example, filename, compileflags) - File "/usr/local/sage/local/bin/ncadoctest.py", line 1172, in run_one_example + File "/usr/local/sage/local/bin/ncadoctest.py", line 1172, in run_one_example compileflags, 1) in test.globs - File "", line 1, in + File "", line 1, in next(h.solve(algorithm='backtrack'))###line 515: sage: next(h.solve(algorithm='backtrack')) - File "/home/jdemeyer/.sage/tmp/sudoku.py", line 607, in solve + File "/home/jdemeyer/.sage/tmp/sudoku.py", line 607, in solve for soln in gen: - File "/home/jdemeyer/.sage/tmp/sudoku.py", line 719, in backtrack + File "/home/jdemeyer/.sage/tmp/sudoku.py", line 719, in backtrack from sudoku_backtrack import backtrack_all ImportError: No module named sudoku_backtrack ********************************************************************** [...more errors...] 2 items had failures: - 4 of 15 in __main__.example_13 - 2 of 8 in __main__.example_14 + 4 of 15 in __main__.example_13 + 2 of 8 in __main__.example_14 ***Test Failed*** 6 failures. For whitespace errors, see the file /home/jdemeyer/.sage//tmp/.doctest_sudoku.py - [21.1 s] + [21.1 s] ---------------------------------------------------------------------- The following tests failed: @@ -213,9 +227,11 @@ of our system for parallel testing. Let us doctest all modules in a directory, first using a single thread and then using four threads. For this example, suppose we want to test all the modules under ``sage/crypto/``. We can use a syntax similar to -that shown above to achieve this:: +that shown above to achieve this - [jdemeyer@localhost sage]$ ./sage -t src/sage/crypto +.. code-block:: console + + $ ./sage -t src/sage/crypto Running doctests with ID 2012-07-03-03-45-40-7f837dcf. Doctesting 24 files. sage -t src/sage/crypto/__init__.py @@ -274,9 +290,11 @@ that shown above to achieve this:: cumulative wall time: 35.1 seconds Now we do the same thing, but this time we also use the optional -argument ``--long``:: +argument ``--long`` + +.. code-block:: console - [jdemeyer@localhost sage]$ ./sage -t --long src/sage/crypto/ + $ ./sage -t --long src/sage/crypto/ Running doctests with ID 2012-07-03-03-48-11-c16721e6. Doctesting 24 files. sage -t --long src/sage/crypto/__init__.py @@ -344,7 +362,7 @@ through all tests in that module. Here is a snippet of a function in the module ``sage/crypto/mq/sr.py`` with a doctest that has been flagged as taking a long time: -.. CODE-BLOCK:: python +.. code-block:: python def test_consistency(max_n=2, **kwargs): r""" @@ -370,9 +388,11 @@ as taking a long time: True """ -Now we doctest the same directory in parallel using 4 threads:: +Now we doctest the same directory in parallel using 4 threads - [jdemeyer@localhost sage]$ ./sage -tp 4 src/sage/crypto/ +.. code-block:: console + + $ ./sage -tp 4 src/sage/crypto/ Running doctests with ID 2012-07-07-00-11-55-9b17765e. Sorting sources by runtime so that slower doctests are run first.... Doctesting 24 files using 4 threads. @@ -430,7 +450,7 @@ Now we doctest the same directory in parallel using 4 threads:: Total time for all tests: 12.9 seconds cpu time: 30.5 seconds cumulative wall time: 31.7 seconds - [jdemeyer@localhost sage]$ ./sage -tp 4 --long src/sage/crypto/ + $ ./sage -tp 4 --long src/sage/crypto/ Running doctests with ID 2012-07-07-00-13-04-d71f3cd4. Sorting sources by runtime so that slower doctests are run first.... Doctesting 24 files using 4 threads. @@ -502,9 +522,11 @@ The main Sage library resides in the directory :sage_root:`src/`. We can use the syntax described above to doctest the main library using multiple threads. When doing release management or patching the main Sage library, a release manager would -parallel test the library using 10 threads with the following command:: +parallel test the library using 10 threads with the following command + +.. code-block:: console - [jdemeyer@localhost sage]$ ./sage -tp 10 --long src/ + $ ./sage -tp 10 --long src/ Another way is run ``make ptestlong``, which builds Sage (if necessary), builds the Sage documentation (if necessary), and then runs parallel @@ -517,14 +539,16 @@ the number of CPU cores (as determined by the Python function `_, then Sage will request as most this number of job slots.) -In any case, this will test the Sage library with multiple threads:: +In any case, this will test the Sage library with multiple threads - [jdemeyer@localhost sage]$ make ptestlong +.. code-block:: console + + $ make ptestlong Any of the following commands would also doctest the Sage library or one of its clones: -.. CODE-BLOCK:: text +.. code-block:: text make test make check @@ -578,9 +602,11 @@ Beyond the Sage library Doctesting also works fine for files not in the Sage library. For example, suppose we have a Python script called -``my_python_script.py``:: +``my_python_script.py`` + +.. code-block:: console - [mvngu@localhost sage]$ cat my_python_script.py + $ cat my_python_script.py from sage.all_cmdline import * # import sage library def square(n): @@ -594,9 +620,11 @@ example, suppose we have a Python script called """ return n**2 -Then we can doctest it just as with Sage library files:: +Then we can doctest it just as with Sage library files + +.. code-block:: console - [mvngu@localhost sage]$ ./sage -t my_python_script.py + $ ./sage -t my_python_script.py Running doctests with ID 2012-07-07-00-17-56-d056f7c0. Doctesting 1 file. sage -t my_python_script.py @@ -609,9 +637,11 @@ Then we can doctest it just as with Sage library files:: cumulative wall time: 0.0 seconds Doctesting can also be performed on Sage scripts. Say we have a Sage -script called ``my_sage_script.sage`` with the following content:: +script called ``my_sage_script.sage`` with the following content - [mvngu@localhost sage]$ cat my_sage_script.sage +.. code-block:: console + + $ cat my_sage_script.sage def cube(n): r""" Return the cube of n. @@ -623,9 +653,11 @@ script called ``my_sage_script.sage`` with the following content:: """ return n**3 -Then we can doctest it just as for Python files:: +Then we can doctest it just as for Python files + +.. code-block:: console - [mvngu@localhost sage]$ ./sage -t my_sage_script.sage + $ ./sage -t my_sage_script.sage Running doctests with ID 2012-07-07-00-20-06-82ee728c. Doctesting 1 file. sage -t my_sage_script.sage @@ -638,10 +670,12 @@ Then we can doctest it just as for Python files:: cumulative wall time: 0.0 seconds Alternatively, we can preparse it to convert it to a Python script, -and then doctest that:: +and then doctest that - [mvngu@localhost sage]$ ./sage --preparse my_sage_script.sage - [mvngu@localhost sage]$ cat my_sage_script.sage.py +.. code-block:: console + + $ ./sage --preparse my_sage_script.sage + $ cat my_sage_script.sage.py # This file was *autogenerated* from the file my_sage_script.sage. from sage.all_cmdline import * # import sage library _sage_const_3 = Integer(3) @@ -655,7 +689,7 @@ and then doctest that:: 8 """ return n**_sage_const_3 - [mvngu@localhost sage]$ ./sage -t my_sage_script.sage.py + $ ./sage -t my_sage_script.sage.py Running doctests with ID 2012-07-07-00-26-46-2bb00911. Doctesting 1 file. sage -t my_sage_script.sage.py @@ -675,7 +709,7 @@ You can run doctests from within Sage, which can be useful since you don't have to wait for Sage to start. Use the ``run_doctests`` function in the global namespace, passing it either a string or a module: -.. CODE-BLOCK:: ipycon +.. code-block:: ipycon sage: run_doctests(sage.combinat.affine_permutation) Running doctests with ID 2018-02-07-13-23-13-89fe17b1. @@ -704,7 +738,7 @@ Ideally, doctests should not take any noticeable amount of time. If you really need longer-running doctests (anything beyond about one second) then you should mark them as: -.. CODE-BLOCK:: text +.. code-block:: text sage: my_long_test() # long time @@ -717,9 +751,11 @@ the code. Use the ``--long`` flag to run doctests that have been marked with the comment ``# long time``. These tests are normally skipped in order to -reduce the time spent running tests:: +reduce the time spent running tests + +.. code-block:: console - [roed@localhost sage]$ ./sage -t src/sage/rings/tests.py + $ ./sage -t src/sage/rings/tests.py Running doctests with ID 2012-06-21-16-00-13-40835825. Doctesting 1 file. sage -t tests.py @@ -731,9 +767,11 @@ reduce the time spent running tests:: cpu time: 0.9 seconds cumulative wall time: 1.1 seconds -In order to run the long tests as well, do the following:: +In order to run the long tests as well, do the following - [roed@localhost sage]$ ./sage -t --long src/sage/rings/tests.py +.. code-block:: console + + $ ./sage -t --long src/sage/rings/tests.py Running doctests with ID 2012-06-21-16-02-05-d13a9a24. Doctesting 1 file. sage -t tests.py @@ -748,9 +786,11 @@ In order to run the long tests as well, do the following:: To find tests that take longer than a specified amount of CPU time, use the ``--warn-long`` flag. Without any options, it will cause a warning to be printed if any tests take longer than one -cpu-second. Note that this is a warning, not an error:: +cpu-second. Note that this is a warning, not an error + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --warn-long src/sage/rings/factorint.pyx + $ ./sage -t --warn-long src/sage/rings/factorint.pyx Running doctests with ID 2012-07-14-03-27-03-2c952ac1. Doctesting 1 file. sage -t --warn-long src/sage/rings/factorint.pyx @@ -782,9 +822,11 @@ cpu-second. Note that this is a warning, not an error:: cpu time: 9.7 seconds cumulative wall time: 10.9 seconds -You can also pass in an explicit amount of time:: +You can also pass in an explicit amount of time + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --long --warn-long 2.0 src/sage/rings/tests.py + $ ./sage -t --long --warn-long 2.0 src/sage/rings/tests.py Running doctests with ID 2012-07-14-03-30-13-c9164c9d. Doctesting 1 file. sage -t --long --warn-long 2.0 tests.py @@ -809,9 +851,11 @@ You can also pass in an explicit amount of time:: Finally, you can disable any warnings about long tests with ``--warn-long 0``. -Doctests start from a random seed:: +Doctests start from a random seed - [kliem@localhost sage]$ ./sage -t src/sage/doctest/tests/random_seed.rst +.. code-block:: console + + $ ./sage -t src/sage/doctest/tests/random_seed.rst Running doctests with ID 2020-06-23-23-22-59-49f37a55. ... Doctesting 1 file. @@ -826,7 +870,7 @@ Doctests start from a random seed:: 8 ********************************************************************** 1 item had failures: - 1 of 2 in sage.doctest.tests.random_seed + 1 of 2 in sage.doctest.tests.random_seed [1 test, 1 failure, 0.00 s] ---------------------------------------------------------------------- sage -t --warn-long 89.5 --random-seed=112986622569797306072457879734474628454 src/sage/doctest/tests/random_seed.rst # 1 doctest failed @@ -835,11 +879,13 @@ Doctests start from a random seed:: cpu time: 0.0 seconds cumulative wall time: 0.0 seconds -This seed can be set explicitly to reproduce possible failures:: +This seed can be set explicitly to reproduce possible failures + +.. code-block:: console - [kliem@localhost sage]$ ./sage -t --warn-long 89.5 \ - --random-seed=112986622569797306072457879734474628454 \ - src/sage/doctest/tests/random_seed.rst + $ ./sage -t --warn-long 89.5 \ + --random-seed=112986622569797306072457879734474628454 \ + src/sage/doctest/tests/random_seed.rst Running doctests with ID 2020-06-23-23-24-28-14a52269. ... Doctesting 1 file. @@ -854,7 +900,7 @@ This seed can be set explicitly to reproduce possible failures:: 8 ********************************************************************** 1 item had failures: - 1 of 2 in sage.doctest.tests.random_seed + 1 of 2 in sage.doctest.tests.random_seed [1 test, 1 failure, 0.00 s] ---------------------------------------------------------------------- sage -t --warn-long 89.5 --random-seed=112986622569797306072457879734474628454 src/sage/doctest/tests/random_seed.rst # 1 doctest failed @@ -876,10 +922,12 @@ You can run tests that require optional packages by using the ``--optional`` flag. Obviously, you need to have installed the necessary optional packages in order for these tests to succeed. -By default, Sage only runs doctests that are not marked with the ``optional`` tag. This is equivalent to running :: +By default, Sage only runs doctests that are not marked with the ``optional`` tag. This is equivalent to running - [roed@localhost sage]$ ./sage -t --optional=sagemath_doc_html,sage \ - src/sage/rings/real_mpfr.pyx +.. code-block:: console + + $ ./sage -t --optional=sagemath_doc_html,sage \ + src/sage/rings/real_mpfr.pyx Running doctests with ID 2012-06-21-16-18-30-a368a200. Doctesting 1 file. sage -t src/sage/rings/real_mpfr.pyx @@ -891,10 +939,12 @@ By default, Sage only runs doctests that are not marked with the ``optional`` ta cpu time: 4.1 seconds cumulative wall time: 7.0 seconds -If you want to also run tests that require magma, you can do the following:: +If you want to also run tests that require magma, you can do the following + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --optional=sagemath_doc_html,sage,magma \ - src/sage/rings/real_mpfr.pyx + $ ./sage -t --optional=sagemath_doc_html,sage,magma \ + src/sage/rings/real_mpfr.pyx Running doctests with ID 2012-06-21-16-18-30-a00a7319 Doctesting 1 file. sage -t src/sage/rings/real_mpfr.pyx @@ -906,9 +956,11 @@ If you want to also run tests that require magma, you can do the following:: cpu time: 4.0 seconds cumulative wall time: 8.4 seconds -In order to just run the tests that are marked as requiring magma, omit ``sage`` and ``sagemath_doc_html``:: +In order to just run the tests that are marked as requiring magma, omit ``sage`` and ``sagemath_doc_html`` - [roed@localhost sage]$ ./sage -t --optional=magma src/sage/rings/real_mpfr.pyx +.. code-block:: console + + $ ./sage -t --optional=magma src/sage/rings/real_mpfr.pyx Running doctests with ID 2012-06-21-16-18-33-a2bc1fdf Doctesting 1 file. sage -t src/sage/rings/real_mpfr.pyx @@ -922,9 +974,11 @@ In order to just run the tests that are marked as requiring magma, omit ``sage`` If you want Sage to detect external software or other capabilities (such as magma, latex, internet) automatically and run all of the -relevant tests, then add ``external``:: +relevant tests, then add ``external`` + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --optional=external src/sage/rings/real_mpfr.pyx + $ ./sage -t --optional=external src/sage/rings/real_mpfr.pyx Running doctests with ID 2016-03-16-14-10-21-af2ebb67. Using --optional=external External software to be detected: cplex,gurobi,internet,latex,macaulay2,magma,maple,mathematica,matlab,octave,scilab @@ -939,9 +993,11 @@ relevant tests, then add ``external``:: cumulative wall time: 0.0 seconds External software detected for doctesting: magma -To run all tests, regardless of whether they are marked optional, pass ``all`` as the ``optional`` tag:: +To run all tests, regardless of whether they are marked optional, pass ``all`` as the ``optional`` tag + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --optional=all src/sage/rings/real_mpfr.pyx + $ ./sage -t --optional=all src/sage/rings/real_mpfr.pyx Running doctests with ID 2012-06-21-16-31-18-8c097f55 Doctesting 1 file. sage -t src/sage/rings/real_mpfr.pyx @@ -960,9 +1016,11 @@ Running doctests in parallel If you're testing many files, you can get big speedups by using more than one thread. To run doctests in parallel use the ``--nthreads`` flag (``-p`` is a shortened version). Pass in the number of threads -you would like to use (by default Sage just uses 1):: +you would like to use (by default Sage just uses 1) - [roed@localhost sage]$ ./sage -tp 2 src/sage/doctest/ +.. code-block:: console + + $ ./sage -tp 2 src/sage/doctest/ Running doctests with ID 2012-06-22-19-09-25-a3afdb8c. Sorting sources by runtime so that slower doctests are run first.... Doctesting 8 files using 2 threads. @@ -996,9 +1054,11 @@ Doctesting all of Sage To doctest the whole Sage library use the ``--all`` flag (``-a`` for short). In addition to testing the code in Sage's Python and Cython files, this command will run the tests defined in Sage's documentation -as well as testing the Sage notebook:: +as well as testing the Sage notebook + +.. code-block:: console - [roed@localhost sage]$ ./sage -t -a + $ ./sage -t -a Running doctests with ID 2012-06-22-19-10-27-e26fce6d. Doctesting entire Sage library. Sorting sources by runtime so that slower doctests are run first.... @@ -1017,10 +1077,12 @@ produces a Python error, then normally tests continue after reporting that an error occurred. If you use the flag ``--debug`` (``-d`` for short) then you will drop into an interactive Python debugger whenever a Python exception occurs. As an example, I modified -:mod:`sage.schemes.elliptic_curves.constructor` to produce an error:: +:mod:`sage.schemes.elliptic_curves.constructor` to produce an error - [roed@localhost sage]$ ./sage -t --debug \ - src/sage/schemes/elliptic_curves/constructor.py +.. code-block:: console + + $ ./sage -t --debug \ + src/sage/schemes/elliptic_curves/constructor.py Running doctests with ID 2012-06-23-12-09-04-b6352629. Doctesting 1 file. ********************************************************************** @@ -1029,19 +1091,19 @@ a Python exception occurs. As an example, I modified EllipticCurve([0,0]) Exception raised: Traceback (most recent call last): - File ".../site-packages/sage/doctest/forker.py", line 573, in _run + File ".../site-packages/sage/doctest/forker.py", line 573, in _run self.execute(example, compiled, test.globs) - File ".../site-packages/sage/doctest/forker.py", line 835, in execute + File ".../site-packages/sage/doctest/forker.py", line 835, in execute exec compiled in globs - File "", line 1, in + File "", line 1, in EllipticCurve([Integer(0),Integer(0)]) - File ".../site-packages/sage/schemes/elliptic_curves/constructor.py", line 346, in EllipticCurve + File ".../site-packages/sage/schemes/elliptic_curves/constructor.py", line 346, in EllipticCurve return ell_rational_field.EllipticCurve_rational_field(x, y) - File ".../site-packages/sage/schemes/elliptic_curves/ell_rational_field.py", line 216, in __init__ + File ".../site-packages/sage/schemes/elliptic_curves/ell_rational_field.py", line 216, in __init__ EllipticCurve_number_field.__init__(self, Q, ainvs) - File ".../site-packages/sage/schemes/elliptic_curves/ell_number_field.py", line 159, in __init__ + File ".../site-packages/sage/schemes/elliptic_curves/ell_number_field.py", line 159, in __init__ EllipticCurve_field.__init__(self, [field(x) for x in ainvs]) - File ".../site-packages/sage/schemes/elliptic_curves/ell_generic.py", line 156, in __init__ + File ".../site-packages/sage/schemes/elliptic_curves/ell_generic.py", line 156, in __init__ "Invariants %s define a singular curve."%ainvs ArithmeticError: Invariants [0, 0, 0, 0, 0] define a singular curve. > .../site-packages/sage/schemes/elliptic_curves/ell_generic.py(156)__init__() @@ -1063,7 +1125,7 @@ a Python exception occurs. As an example, I modified (Pdb) quit ********************************************************************** 1 items had failures: - 1 of 1 in sage.schemes.elliptic_curves.constructor + 1 of 1 in sage.schemes.elliptic_curves.constructor ***Test Failed*** 1 failures. sage -t src/sage/schemes/elliptic_curves/constructor.py [64 tests, 89.2 s] @@ -1079,10 +1141,12 @@ or hang. In such a situation you have a number of options. The doctest framework will print out the output so far, so that at least you know what test caused the problem (if you want this output to appear in real time use the ``--verbose`` flag). To have doctests run -under the control of gdb, use the ``--gdb`` flag:: +under the control of gdb, use the ``--gdb`` flag + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --gdb \ - src/sage/schemes/elliptic_curves/constructor.py + $ ./sage -t --gdb \ + src/sage/schemes/elliptic_curves/constructor.py exec gdb --eval-commands="run" --args /home/roed/sage/local/var/lib/sage/venv-python3.9/bin/python3 sage-runtests --serial --timeout=0 --stats-path=/home/roed/.sage/timings2.json --optional=pip,sage,sage_spkg src/sage/schemes/elliptic_curves/constructor.py GNU gdb 6.8-debian Copyright (C) 2008 Free Software Foundation, Inc. @@ -1115,9 +1179,11 @@ valgrind tools to track down memory issues: the relevant flags are Once you're done fixing whatever problems where revealed by the doctests, you can rerun just those files that failed their most recent -test by using the ``--failed`` flag (``-f`` for short):: +test by using the ``--failed`` flag (``-f`` for short) - [roed@localhost sage]$ ./sage -t -fa +.. code-block:: console + + $ ./sage -t -fa Running doctests with ID 2012-07-07-00-45-35-d8b5a408. Doctesting entire Sage library. Only doctesting files that failed last test. @@ -1143,25 +1209,27 @@ Show skipped optional tests ^^^^^^^^^^^^^^^^^^^^^^^^^^^ To print a summary at the end of each file with the number of optional -tests skipped, use the ``--show-skipped`` flag:: - - [roed@localhost sage]$ ./sage -t --show-skipped \ - src/sage/rings/finite_rings/integer_mod.pyx - Running doctests with ID 2013-03-14-15-32-05-8136f5e3. - Doctesting 1 file. - sage -t sage/rings/finite_rings/integer_mod.pyx - 2 axiom tests not run - 1 cunningham test not run - 2 fricas tests not run - 1 long test not run - 3 magma tests not run - [440 tests, 4.0 s] - ---------------------------------------------------------------------- - All tests passed! - ---------------------------------------------------------------------- - Total time for all tests: 4.3 seconds - cpu time: 2.4 seconds - cumulative wall time: 4.0 seconds +tests skipped, use the ``--show-skipped`` flag + +.. code-block:: console + + $ ./sage -t --show-skipped \ + src/sage/rings/finite_rings/integer_mod.pyx + Running doctests with ID 2013-03-14-15-32-05-8136f5e3. + Doctesting 1 file. + sage -t sage/rings/finite_rings/integer_mod.pyx + 2 axiom tests not run + 1 cunningham test not run + 2 fricas tests not run + 1 long test not run + 3 magma tests not run + [440 tests, 4.0 s] + ---------------------------------------------------------------------- + All tests passed! + ---------------------------------------------------------------------- + Total time for all tests: 4.3 seconds + cpu time: 2.4 seconds + cumulative wall time: 4.0 seconds Running tests with iterations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1169,9 +1237,11 @@ Running tests with iterations Sometimes tests fail intermittently. There are two options that allow you to run tests repeatedly in an attempt to search for Heisenbugs. The flag ``--global-iterations`` takes an integer and runs the whole -set of tests that many times serially:: +set of tests that many times serially - [roed@localhost sage]$ ./sage -t --global-iterations 2 src/sage/sandpiles +.. code-block:: console + + $ ./sage -t --global-iterations 2 src/sage/sandpiles Running doctests with ID 2012-07-07-00-59-28-e7048ad9. Doctesting 3 files (2 global iterations). sage -t src/sage/sandpiles/__init__.py @@ -1200,9 +1270,11 @@ set of tests that many times serially:: cumulative wall time: 28.5 seconds You can also iterate in a different order: the ``--file-iterations`` -flag runs the tests in each file ``N`` times before proceeding:: +flag runs the tests in each file ``N`` times before proceeding + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --file-iterations 2 src/sage/sandpiles + $ ./sage -t --file-iterations 2 src/sage/sandpiles Running doctests with ID 2012-07-07-01-01-43-8f954206. Doctesting 3 files (2 file iterations). sage -t src/sage/sandpiles/__init__.py @@ -1228,9 +1300,11 @@ Using a different timeout On a slow machine the default timeout of 5 minutes may not be enough for the slowest files. Use the ``--timeout`` flag (``-T`` for short) -to set it to something else:: +to set it to something else + +.. code-block:: console - [roed@localhost sage]$ ./sage -tp 2 --all --timeout 1 + $ ./sage -tp 2 --all --timeout 1 Running doctests with ID 2012-07-07-01-09-37-deb1ab83. Doctesting entire Sage library. Sorting sources by runtime so that slower doctests are run first.... @@ -1243,9 +1317,11 @@ Using absolute paths ^^^^^^^^^^^^^^^^^^^^ By default filenames are printed using relative paths. To use -absolute paths instead pass in the ``--abspath`` flag:: +absolute paths instead pass in the ``--abspath`` flag - [roed@localhost sage]$ ./sage -t --abspath src/sage/doctest/control.py +.. code-block:: console + + $ ./sage -t --abspath src/sage/doctest/control.py Running doctests with ID 2012-07-07-01-13-03-a023e212. Doctesting 1 file. sage -t /home/roed/sage/src/sage/doctest/control.py @@ -1264,9 +1340,11 @@ Testing changed files If you are working on some files in the Sage library it can be convenient to test only the files that have changed. To do so use the ``--new`` flag, which tests files that have been modified or added -since the last commit:: +since the last commit + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --new + $ ./sage -t --new Running doctests with ID 2012-07-07-01-15-52-645620ee. Doctesting files changed since last git commit. Doctesting 1 file. @@ -1285,9 +1363,11 @@ Running tests in a random order By default, tests are run in the order in which they appear in the file. To run tests in a random order (which can reveal subtle bugs), -use the ``--randorder`` flag and pass in a random seed:: +use the ``--randorder`` flag and pass in a random seed - [roed@localhost sage]$ ./sage -t --new --randorder 127 +.. code-block:: console + + $ ./sage -t --new --randorder 127 Running doctests with ID 2012-07-07-01-19-06-97c8484e. Doctesting files changed since last git commit. Doctesting 1 file. @@ -1317,9 +1397,11 @@ Auxiliary files ^^^^^^^^^^^^^^^ To specify a logfile (rather than use the default which is created for -``sage -t --all``), use the ``--logfile`` flag:: +``sage -t --all``), use the ``--logfile`` flag + +.. code-block:: console - [roed@localhost sage]$ ./sage -t --logfile test1.log src/sage/doctest/control.py + $ ./sage -t --logfile test1.log src/sage/doctest/control.py Running doctests with ID 2012-07-07-01-25-49-e7c0e52d. Doctesting 1 file. sage -t src/sage/doctest/control.py @@ -1330,7 +1412,7 @@ To specify a logfile (rather than use the default which is created for Total time for all tests: 6.7 seconds cpu time: 0.1 seconds cumulative wall time: 4.3 seconds - [roed@localhost sage]$ cat test1.log + $ cat test1.log Running doctests with ID 2012-07-07-01-25-49-e7c0e52d. Doctesting 1 file. sage -t src/sage/doctest/control.py @@ -1347,9 +1429,11 @@ To give a json file storing the timings and pass/fail status for each file, use ``--stats-path`` flag; the default location of this file is ``~/.sage/timings2.json``. The doctester reads it if it exists, for the purpose of sorting the files so that slower tests are run first (and thus multiple processes are utilized most -efficiently):: +efficiently) - [roed@localhost sage]$ ./sage -tp 2 --stats-path ~/.sage/timings2.json --all +.. code-block:: console + + $ ./sage -tp 2 --stats-path ~/.sage/timings2.json --all Running doctests with ID 2012-07-07-01-28-34-2df4251d. Doctesting entire Sage library. Sorting sources by runtime so that slower doctests are run first.... @@ -1387,10 +1471,12 @@ The virtual environments, set up in directories such as contain installations of built (non-editable) wheels. To test all modules of Sage that are installed in a virtual environment, -use the option ``--installed`` (instead of ``--all``):: +use the option ``--installed`` (instead of ``--all``) + +.. code-block:: console - [mkoeppe@localhost sage]$ pkgs/sagemath-standard/.tox/sagepython-.../sage -t \ - -p4 --installed + $ pkgs/sagemath-standard/.tox/sagepython-.../sage -t \ + -p4 --installed This tests against the doctests as they appear in the installed copies of the files (in ``site-packages/sage/...``). @@ -1409,10 +1495,12 @@ Updating doctest outputs ------------------------ By default, ``./sage --fixdoctests`` runs the doctester and replaces the expected outputs -of all examples by the actual outputs from the current version of Sage:: +of all examples by the actual outputs from the current version of Sage + +.. code-block:: console - [mkoeppe@localhost sage]$ ./sage --fixdoctests \ - --overwrite src/sage/arith/weird.py + $ ./sage --fixdoctests \ + --overwrite src/sage/arith/weird.py For example, when applied to this Python file:: @@ -1471,10 +1559,12 @@ the tracebacks using ``...``. The doctest fixer uses this abbreviation automati when formatting the actual output, as shown in the above example. To disable it so that the details of the exception can be inspected, use the option ``--full-tracebacks``. This is particularly useful -in combination with ``--keep-both``:: +in combination with ``--keep-both`` - [mkoeppe@localhost sage]$ ./sage --fixdoctests --keep-both --full-tracebacks \ - --overwrite src/sage/arith/weird.py +.. code-block:: console + + $ ./sage --fixdoctests --keep-both --full-tracebacks \ + --overwrite src/sage/arith/weird.py This will give the following result on the above example:: @@ -1500,17 +1590,21 @@ This will give the following result on the above example:: | ... | """ -To make sure that all doctests are updated, you may have to use the option ``--long``:: +To make sure that all doctests are updated, you may have to use the option ``--long`` + +.. code-block:: console - [mkoeppe@localhost sage]$ ./sage --fixdoctests --long \ - --overwrite src/sage/arith/weird.py + $ ./sage --fixdoctests --long \ + --overwrite src/sage/arith/weird.py If you are not comfortable with allowing this tool to edit your source files, you can use the option ``--no-overwrite``, which will create a new file with the extension ``.fixed`` -instead of overwriting the source file:: +instead of overwriting the source file + +.. code-block:: console - [mkoeppe@localhost sage]$ ./sage --fixdoctests \ - --no-overwrite src/sage/arith/weird.py + $ ./sage --fixdoctests \ + --no-overwrite src/sage/arith/weird.py .. _section-fixdoctests-optional-needs: @@ -1637,19 +1731,23 @@ Use in virtual environments --------------------------- The doctest fixer can also run tests using the Sage doctester installed in -a virtual environment:: +a virtual environment - [mkoeppe@localhost sage]$ ./sage --fixdoctests --overwrite \ - --distribution sagemath-categories \ - src/sage/geometry/schemes/generic/*.py +.. code-block:: console + + $ ./sage --fixdoctests --overwrite \ + --distribution sagemath-categories \ + src/sage/geometry/schemes/generic/*.py This command, using ``--distribution``, is equivalent to a command -that uses the more specific options ``--venv`` and ``--environment``:: +that uses the more specific options ``--venv`` and ``--environment`` + +.. code-block:: console - [mkoeppe@localhost sage]$ ./sage --fixdoctests --overwrite \ - --venv pkgs/sagemath-categories/.tox/sagepython-... \ - --environment sage.all__sagemath_categories - src/sage/geometry/schemes/generic/*.py + $ ./sage --fixdoctests --overwrite \ + --venv pkgs/sagemath-categories/.tox/sagepython-... \ + --environment sage.all__sagemath_categories \ + src/sage/geometry/schemes/generic/*.py Either way, the options ``--keep-both``, ``--full-tracebacks``, and ``--if-installed`` are implied. @@ -1681,7 +1779,9 @@ with the option ``--baseline-stats-path``, see section After running the doctesters of the distributions, for example, via ``sage --fixdoctests``, you can use the test results stored in ``timings2.json`` files to update the ``known-test-failures*.json`` files. -This update can be done using the command:: +This update can be done using the command + +.. code-block:: console - [mkoeppe@localhost sage]$ ./sage --fixdoctests --no-test \ - --update-known-test-failures --distribution all + $ ./sage --fixdoctests --no-test \ + --update-known-test-failures --distribution all diff --git a/src/doc/en/developer/downstream.rst b/src/doc/en/developer/downstream.rst index f2eb8c98a1a..e9a9e9725bd 100644 --- a/src/doc/en/developer/downstream.rst +++ b/src/doc/en/developer/downstream.rst @@ -5,10 +5,6 @@ Packaging SageMath Downstream This document is intended for downstream maintainers (e.g., Linux distribution package maintainers) who wish to create redistributable builds of Sage. -.. contents:: - :local: - :depth: 2 - Dependencies ============ @@ -17,15 +13,15 @@ provided by the downstream distribution. The definitive list of dependencies is found in `pyproject.toml `_. These include: - - `build-system.requires`: Python packages needed for building SageMath, - - `project.dependencies`: Python packages required at runtime, - - `project.optional-dependencies`: optional dependencies for additional + - ``build-system.requires``: Python packages needed for building SageMath, + - ``project.dependencies``: Python packages required at runtime, + - ``project.optional-dependencies``: optional dependencies for additional functionality, - - `external.build-requires` and `external.host-requires`: system dependencies + - ``external.build-requires`` and ``external.host-requires``: system dependencies needed for building, - - `external.dependencies`: system libraries required at runtime. + - ``external.dependencies``: system libraries required at runtime. -The `external` section follows `PEP 725 `_ +The ``external`` section follows `PEP 725 `_ and specifies dependencies in the form of ̀PURLs. At the moment, there is no standard interface to translate these PURLs into system package names. However, the names should be quite self-explanatory. @@ -37,52 +33,49 @@ Build Procedure =============== 1. **Obtain the Source**: - Clone the SageMath repository: + Clone the SageMath repository: - .. code-block:: bash + .. code-block:: console - git clone https://github.com/sagemath/sage.git + $ git clone https://github.com/sagemath/sage.git Alternatively, download the sdist tarball from the - `SageMath PyPI project`_ or from the + `SageMath PyPI project `_ or from the `GitHub releases `_. -1. **Prepare the Build Environment**: - Ensure a clean and consistent build environment with access to all - required system libraries and Python packages. - -2. **Build**: +2. **Prepare the Build Environment**: + Ensure a clean and consistent build environment with access to all + required system libraries and Python packages. - Create a wheel using the `build` module: +3. **Build**: + Create a wheel using the ``build`` module: - .. code-block:: bash + .. code-block:: console - python -m build --wheel --no-isolation + $ python -m build --wheel --no-isolation If you are sure that all dependencies are available, you may also add the - `--skip-dependency-check` option. + ``--skip-dependency-check`` option. Moreover, if you care about reproducible builds, it is recommended to - use `-Cbuild-dir=build` to specify a build directory, see this + use ``-Cbuild-dir=build`` to specify a build directory, see this `Meson-Python issue `_. -3. **Install**: - +4. **Install**: The resulting wheel can be installed using - .. code-block:: bash + .. code-block:: console - python -m installer --destdir="" dist/sagemath-*.whl + $ python -m installer --destdir="" dist/sagemath-*.whl - where `` is the directory where you want to install the package - (usually a temporary directory for packaging). + where ```` is the directory where you want to install the package + (usually a temporary directory for packaging). 4. **Test the Build**: + Run the Sage tests to ensure functionality: - Run the Sage tests to ensure functionality: - - .. code-block:: bash + .. code-block:: console - python -m sage.doctest --all + $ python -m sage.doctest --all However, some tests are known to fail, see :issue:`39872`. @@ -92,7 +85,7 @@ that may benefit others, please consider contributing back by reporting issues or opening pull requests on the SageMath GitHub repository. Other considerations: -- **Package naming**: Use `sagemath`, or `python-sagemath` if your distribution +- **Package naming**: Use ``sagemath``, or ``python-sagemath`` if your distribution has a convention for Python packages. Example Downstream Packages diff --git a/src/doc/en/developer/git_advanced.rst b/src/doc/en/developer/git_advanced.rst index 0848e3ea2e7..35d0023e996 100644 --- a/src/doc/en/developer/git_advanced.rst +++ b/src/doc/en/developer/git_advanced.rst @@ -22,9 +22,11 @@ secretly the branch is just a shortcut for a particular commit, the head commit of the branch. But you can just go to a particular commit without a branch, this is called "detached head". If you have the commit already in your local history, you can directly check it -out without requiring internet access:: +out without requiring internet access - [alice@localhost sage]$ git checkout f9a0d54099d758ccec731a38929902b2b9d0b988 +.. code-block:: console + + $ git checkout f9a0d54099d758ccec731a38929902b2b9d0b988 Note: switching to 'f9a0d54099d758ccec731a38929902b2b9d0b988'. You are in 'detached HEAD' state. You can look around, make experimental @@ -45,18 +47,22 @@ out without requiring internet access:: HEAD is now at f9a0d54099 Fix a slow doctest in matrix_integer_dense_hnf.py If it is not stored in your local Git repository, you need to download -it from the ``upstream`` repo first:: +it from the ``upstream`` repo first + +.. code-block:: console - [alice@localhost sage]$ git fetch upstream f9a0d54099d758ccec731a38929902b2b9d0b988 + $ git fetch upstream f9a0d54099d758ccec731a38929902b2b9d0b988 From https://github.com/sagemath/sage * branch f9a0d54099d758ccec731a38929902b2b9d0b988 -> FETCH_HEAD - [alice@localhost sage]$ git checkout FETCH_HEAD + $ git checkout FETCH_HEAD HEAD is now at f9a0d54099 Fix a slow doctest in matrix_integer_dense_hnf.py Either way, you end up with your current HEAD and working directory -that is not associated to any local branch:: +that is not associated to any local branch + +.. code-block:: console - [alice@localhost sage]$ git status + $ git status HEAD detached at f9a0d54099 nothing to commit, working tree clean @@ -113,9 +119,10 @@ Merge in the latest Sage version Suppose we are on our current working branch ``some_code`` (branch is checked out). Then -:: - git merge develop +.. code-block:: console + + $ git merge develop does the merging, i.e. we merge the latest development version into our working branch. @@ -134,37 +141,47 @@ branch ``some_code``, that we want to bring onto this SageMath version (without triggering unnecessary recompilations). We first create a new working tree in a directory ``new_worktree`` and switch -to this directory:: +to this directory + +.. code-block:: console - [alice@localhost sage]$ git worktree add new_worktree - [alice@localhost sage]$ cd new_worktree + $ git worktree add new_worktree + $ cd new_worktree Here we have a new copy of our source files. Thus no timestamps -etc. of the original repository will be changed. Now we do the merge:: +etc. of the original repository will be changed. Now we do the merge + +.. code-block:: console - [alice@localhost sage/new_worktree]$ git checkout some_code - [alice@localhost sage/new_worktree]$ git merge develop + $ git checkout some_code + $ git merge develop -And go back to our original repository:: +And go back to our original repository - [alice@localhost sage/new_worktree]$ git checkout develop - [alice@localhost sage/new_worktree]$ cd .. +.. code-block:: console -We can now safely checkout ``some_code``:: + $ git checkout develop + $ cd .. - [alice@localhost sage]$ git checkout some_code +We can now safely checkout ``some_code`` + +.. code-block:: console + + $ git checkout some_code We still need to call -:: - [alice@localhost sage]$ make +.. code-block:: console + + $ make but only changed files will be recompiled. To remove the new working tree simply use -:: - [alice@localhost sage]$ rm -r new_worktree +.. code-block:: console + + $ rm -r new_worktree Why not merging the other way round? @@ -188,9 +205,11 @@ Git makes it very hard to truly mess up. Here is a short way to get back onto your feet, no matter what. First, if you just want to go back to a working Sage installation you can always abandon your working branch by switching to your local copy of the ``develop`` -branch:: +branch + +.. code-block:: console - [alice@localhost sage]$ git checkout develop + $ git checkout develop As long as you did not make any changes to the ``develop`` branch directly, this will give you back a working Sage. @@ -198,9 +217,11 @@ directly, this will give you back a working Sage. If you want to keep your branch but go back to a previous commit you can use the *reset* command. For this, look up the commit in the log which is some 40-digit hexadecimal number (the SHA1 hash). Then use -``git reset --hard`` to revert your files back to the previous state:: +``git reset --hard`` to revert your files back to the previous state - [alice@localhost sage]$ git log +.. code-block:: console + + $ git log ... commit eafaedad5b0ae2013f8ae1091d2f1df58b72bae3 Author: First Last @@ -208,7 +229,7 @@ which is some 40-digit hexadecimal number (the SHA1 hash). Then use Commit message ... - [alice@localhost sage]$ git reset --hard eafae + $ git reset --hard eafae .. WARNING:: @@ -223,16 +244,20 @@ Finally, perhaps the ultimate human error recovery tool is the reflog. This is a chronological history of Git operations that you can undo if needed. For example, let us assume we messed up the *git reset* command and went back too far (say, 5 commits back). And, on -top of that, deleted a file and committed that:: +top of that, deleted a file and committed that + +.. code-block:: console - [alice@localhost sage]$ git reset --hard HEAD~5 - [alice@localhost sage]$ git rm sage - [alice@localhost sage]$ git commit -m "I shot myself into my foot" + $ git reset --hard HEAD~5 + $ git rm sage + $ git commit -m "I shot myself into my foot" Now we cannot just checkout the repository from before the reset, -because it is no longer in the history. However, here is the reflog:: +because it is no longer in the history. However, here is the reflog + +.. code-block:: console - [alice@localhost sage]$ git reflog + $ git reflog 2eca2a2 HEAD@{0}: commit: I shot myself into my foot b4d86b9 HEAD@{1}: reset: moving to HEAD~5 af353bb HEAD@{2}: checkout: moving from some_branch to master @@ -241,9 +266,11 @@ because it is no longer in the history. However, here is the reflog:: The ``HEAD@{n}`` revisions are shortcuts for the history of Git operations. Since we want to rewind to before the erroneous *git -reset* command, we just have to reset back into the future:: +reset* command, we just have to reset back into the future - [alice@localhost sage]$ git reset --hard HEAD@{2} +.. code-block:: console + + $ git reset --hard HEAD@{2} .. _section-git-rewriting-history: @@ -262,9 +289,11 @@ rewrite history on branches that you have not yet pushed to a public repo. As an advanced example, consider three commits A, B, C that were made on top of each other. For simplicity, we'll assume they just added a -file named ``file_A.py``, ``file_B.py``, and ``file_C.py`` :: +file named ``file_A.py``, ``file_B.py``, and ``file_C.py`` + +.. code-block:: console - [alice@localhost sage]$ git log --oneline + $ git log --oneline 9621dae added file C 7873447 added file B bf817a5 added file A @@ -273,9 +302,11 @@ file named ``file_A.py``, ``file_B.py``, and ``file_C.py`` :: Now, let's assume that the commit B was really independent and ought to be on a separate ticket. So we want to move it to a new branch, which we'll call ``second_branch``. First, branch off at the base -commit before we added A:: +commit before we added A - [alice@localhost sage]$ git checkout 5b5588e +.. code-block:: console + + $ git checkout 5b5588e Note: checking out '5b5588e'. You are in 'detached HEAD' state. You can look around, make experimental @@ -288,21 +319,23 @@ commit before we added A:: git checkout -b new_branch_name HEAD is now at 5b5588e... base commit - [alice@localhost sage]$ git checkout -b second_branch + $ git checkout -b second_branch Switched to a new branch 'second_branch' - [alice@localhost sage]$ git branch + $ git branch first_branch * second_branch - [alice@localhost sage]$ git log --oneline + $ git log --oneline 5b5588e base commit -Now, we make a copy of commit B in the current branch:: +Now, we make a copy of commit B in the current branch + +.. code-block:: console - [alice@localhost sage]$ git cherry-pick 7873447 + $ git cherry-pick 7873447 [second_branch 758522b] added file B 1 file changed, 1 insertion(+) create mode 100644 file_B.py - [alice@localhost sage]$ git log --oneline + $ git log --oneline 758522b added file B 5b5588e base commit @@ -312,22 +345,26 @@ them from the source branch. So we now have to modify the first branch to exclude commit B, otherwise there will be two commits adding ``file_B.py`` and our two branches would conflict later when they are being merged into Sage. Hence, we first reset the first branch back to -before B was added:: +before B was added + +.. code-block:: console - [alice@localhost sage]$ git checkout first_branch + $ git checkout first_branch Switched to branch 'first_branch' - [alice@localhost sage]$ git reset --hard bf817a5 + $ git reset --hard bf817a5 HEAD is now at bf817a5 added file A Now we still want commit C, so we cherry-pick it again. Note that this works even though commit C is, at this point, not included in any -branch:: +branch - [alice@localhost sage]$ git cherry-pick 9621dae +.. code-block:: console + + $ git cherry-pick 9621dae [first_branch 5844535] added file C 1 file changed, 1 insertion(+) create mode 100644 file_C.py - [alice@localhost sage]$ git log --oneline + $ git log --oneline 5844535 added file C bf817a5 added file A 5b5588e base commit @@ -347,16 +384,18 @@ use the interactive rebase feature. This will open an editor where you can modify the most recent commits. Again, this will naturally modify the hash of all changed commits and all of their children. -Now we start by making an identical branch to the first branch:: +Now we start by making an identical branch to the first branch + +.. code-block:: console - [alice@localhost sage]$ git log --oneline + $ git log --oneline 9621dae added file C 7873447 added file B bf817a5 added file A 5b5588e base commit - [alice@localhost sage]$ git checkout -b second_branch + $ git checkout -b second_branch Switched to a new branch 'second_branch' - [alice@localhost sage]$ git rebase -i HEAD~3 + $ git rebase -i HEAD~3 This will open an editor with the last 3 (corresponding to ``HEAD~3``) commits and instructions for how to modify them: diff --git a/src/doc/en/developer/git_background.rst b/src/doc/en/developer/git_background.rst index dcdde034134..b0ab650f8cd 100644 --- a/src/doc/en/developer/git_background.rst +++ b/src/doc/en/developer/git_background.rst @@ -19,7 +19,7 @@ Configuration tips Your personal Git configurations are saved in the ``~/.gitconfig`` file in your home directory. Here is an example: -.. CODE-BLOCK:: text +.. code-block:: text [user] name = Alice Adventure @@ -29,11 +29,13 @@ file in your home directory. Here is an example: editor = emacs You can edit this file directly or you can use Git to make changes for -you:: +you - [alice@localhost ~]$ git config --global user.name "Alice Adventure" - [alice@localhost ~]$ git config --global user.email alice@wonderland.com - [alice@localhost ~]$ git config --global core.editor vim +.. code-block:: console + + $ git config --global user.name "Alice Adventure" + $ git config --global user.email alice@wonderland.com + $ git config --global core.editor vim Aliases @@ -42,19 +44,21 @@ Aliases Aliases are personal shortcuts for Git commands. For example, you might want to be able to shorten ``git checkout`` to ``git co``. Or you may want to alias ``git diff --color-words`` (which gives a nicely -formatted output of the diff) to ``git wdiff``. You can do this with:: +formatted output of the diff) to ``git wdiff``. You can do this with + +.. code-block:: console - [alice@localhost ~]$ git config --global alias.ci "commit -a" - [alice@localhost ~]$ git config --global alias.co checkout - [alice@localhost ~]$ git config --global alias.st "status -a" - [alice@localhost ~]$ git config --global alias.stat "status -a" - [alice@localhost ~]$ git config --global alias.br branch - [alice@localhost ~]$ git config --global alias.wdiff "diff --color-words" + $ git config --global alias.ci "commit -a" + $ git config --global alias.co checkout + $ git config --global alias.st "status -a" + $ git config --global alias.stat "status -a" + $ git config --global alias.br branch + $ git config --global alias.wdiff "diff --color-words" The above commands will create an ``alias`` section in your ``.gitconfig`` file with contents like this: -.. CODE-BLOCK:: text +.. code-block:: text [alias] ci = commit -a @@ -68,9 +72,11 @@ file with contents like this: Editor ------ -To set the editor to use for editing commit messages, you can use:: +To set the editor to use for editing commit messages, you can use + +.. code-block:: console - [alice@localhost ~]$ git config --global core.editor vim + $ git config --global core.editor vim or set the ``EDITOR`` environment variable. @@ -80,14 +86,16 @@ Merging To enforce summaries when doing merges (``~/.gitconfig`` file again): -.. CODE-BLOCK:: text +.. code-block:: text [merge] log = true -Or from the command line:: +Or from the command line - [alice@localhost ~]$ git config --global merge.log true +.. code-block:: console + + $ git config --global merge.log true .. _section-fancy-log: @@ -98,13 +106,15 @@ Fancy log output Here is an alias to get a fancy log output. It should go in the ``alias`` section of your ``.gitconfig`` file: -.. CODE-BLOCK:: text +.. code-block:: text lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)[%an]%Creset' --abbrev-commit --date=relative -Using this ``lg`` alias gives you the changelog with a colored ASCII graph:: +Using this ``lg`` alias gives you the changelog with a colored ASCII graph + +.. code-block:: console - [alice@localhost ~]$ git lg + $ git lg * 6d8e1ee - (HEAD, origin/my-fancy-feature, my-fancy-feature) NF - a fancy file (45 minutes ago) [Matthew Brett] * d304a73 - (origin/placeholder, placeholder) Merge pull request #48 from hhuuggoo/master (2 weeks ago) [Jonathan Terhorst] |\ diff --git a/src/doc/en/developer/git_basic.rst b/src/doc/en/developer/git_basic.rst index 3de7711091c..dc45a25ab8c 100644 --- a/src/doc/en/developer/git_basic.rst +++ b/src/doc/en/developer/git_basic.rst @@ -36,9 +36,11 @@ can create a key pair with the ``ssh-keygen`` tool. Follow either `the detailed instructions `_ -or the following brief instructions:: +or the following brief instructions - [alice@localhost ~]$ ssh-keygen +.. code-block:: console + + $ ssh-keygen Generating public/private rsa key pair. Enter file in which to save the key (/home/alice/.ssh/id_rsa): Enter passphrase (empty for no passphrase): @@ -81,10 +83,12 @@ Adding your public key for authentication to GitHub Follow the procedure `Adding a new SSH key to your GitHub account `_. -Then check that it works by:: +Then check that it works by + +.. code-block:: console - [alice@localhost sage]$ git remote add origin git@github.com:alice/sage.git - [alice@localhost sage]$ git remote -v + $ git remote add origin git@github.com:alice/sage.git + $ git remote -v origin git@github.com:alice/sage.git (fetch) origin git@github.com:alice/sage.git (push) @@ -94,13 +98,17 @@ Then check that it works by:: Pushing your changes to a remote ================================ -Push your branch to the remote ``origin`` with either :: +Push your branch to the remote ``origin`` with either + +.. code-block:: console + + $ git push --set-upstream origin HEAD:my_branch - [alice@localhost sage]$ git push --set-upstream origin HEAD:my_branch +or -or :: +.. code-block:: console - [alice@localhost sage]$ git push origin HEAD:my_branch + $ git push origin HEAD:my_branch if your branch already has an upstream branch. Here "upstream" means the the remote ``origin``, which is *upstream* to your local Git repo. @@ -120,9 +128,11 @@ make a local copy of the branch. In particular, Git has no concept of directly working with the remote branch, the remotes are only bookmarks for things that you can get from/to the remote server. Hence, the first thing you should do is to get everything from the branch -into your local repository. This is achieved by:: +into your local repository. This is achieved by - [alice@localhost sage]$ git fetch upstream pull/12345/head +.. code-block:: console + + $ git fetch upstream pull/12345/head remote: Enumerating objects: 12, done. remote: Counting objects: 100% (12/12), done. remote: Compressing objects: 100% (3/3), done. @@ -135,9 +145,11 @@ The ``pull/12345/head`` branch refers to the branch of the PR #12345 of the remote ``upstream``. The branch is now temporarily (until you fetch something else) stored in your local Git database under the alias ``FETCH_HEAD``. In the second step, we make it available as a new local branch and switch to it. Your -local branch can have a different name, for example:: +local branch can have a different name, for example + +.. code-block:: console - [alice@localhost sage]$ git checkout -b my_branch FETCH_HEAD + $ git checkout -b my_branch FETCH_HEAD Switched to a new branch 'my_branch' creates a new branch in your local Git repository named ``my_branch`` @@ -157,9 +169,11 @@ downloaded the branch of a PR made by someone else, say Bob, and made some suggestions for improvements on the PR. Now Bob incorporated your suggestions into his branch, and you want to get the added changes to complete your review. Assuming that you originally got your local branch as in -:ref:`section-git-checkout`, you can just issue:: +:ref:`section-git-checkout`, you can just issue + +.. code-block:: console - [bob@localhost sage]$ git pull upstream pull/12345/head + $ git pull upstream pull/12345/head From https://github.com/sagemath/sage * branch refs/pull/35608/head -> FETCH_HEAD Merge made by the 'ort' strategy. @@ -185,16 +199,20 @@ delete them before updating the branch. One way to ensure that you are notified of potential problems is to use ``git pull --ff-only``, which will raise an error if a non-trivial merge would be -required:: +required - [alice@localhost sage]$ git checkout develop - [alice@localhost sage]$ git pull --ff-only upstream develop +.. code-block:: console + + $ git checkout develop + $ git pull --ff-only upstream develop If this pull fails, then something is wrong with the local copy of the -master branch. To switch to the correct Sage master branch, use:: +master branch. To switch to the correct Sage master branch, use + +.. code-block:: console - [alice@localhost sage]$ git checkout develop - [alice@localhost sage]$ git reset --hard upstream/develop + $ git checkout develop + $ git reset --hard upstream/develop .. _section-git-merge: @@ -208,7 +226,7 @@ Let us assume you started ``my_branch`` at commit ``B``. After a while, your branch has advanced to commit ``Z``, but you updated ``develop`` (see :ref:`section-git-pull-develop`) and now your Git history looks like this: -.. CODE-BLOCK:: text +.. code-block:: text X---Y---Z my_branch / @@ -220,14 +238,14 @@ How should you deal with such changes? In principle, there are two ways: new ``develop``. This is called **rebase**, and it rewrites your current branch: - .. CODE-BLOCK:: text + .. code-block:: console - git checkout my_branch - git rebase -i develop + $ git checkout my_branch + $ git rebase -i develop In terms of the commit graph, this results in: - .. CODE-BLOCK:: text + .. code-block:: text X'--Y'--Z' my_branch / @@ -240,22 +258,22 @@ How should you deal with such changes? In principle, there are two ways: **Alternatively**, you can rebase ``my_branch`` while updating ``develop`` at the same time (see :ref:`section-git-pull`): - .. CODE-BLOCK:: text + .. code-block:: console - git checkout my_branch - git pull -r develop + $ git checkout my_branch + $ git pull -r develop * **Merging** your branch with ``develop`` will create a new commit above the two of them: - .. CODE-BLOCK:: text + .. code-block:: console - git checkout my_branch - git merge develop + $ git checkout my_branch + $ git merge develop The result is the following commit graph: - .. CODE-BLOCK:: text + .. code-block:: text X---Y---Z---W my_branch / / @@ -271,10 +289,10 @@ How should you deal with such changes? In principle, there are two ways: **Alternatively**, you can merge ``my_branch`` while updating ``develop`` at the same time (see :ref:`section-git-pull`): - .. CODE-BLOCK:: text + .. code-block:: console - git checkout my_branch - git pull develop + $ git checkout my_branch + $ git pull develop **In case of doubt** use merge rather than rebase. There is less risk involved, and rebase in this case is only useful for branches with a very long history. @@ -289,9 +307,11 @@ Simple conflicts can be easily solved with Git only (see :ref:`section-git-confl For more complicated ones, a range of specialized programs are available. Because the conflict marker includes the hash of the most recent -common parent, you can use a three-way diff:: +common parent, you can use a three-way diff - [alice@laptop]$ git mergetool +.. code-block:: console + + $ git mergetool This message is displayed because 'merge.tool' is not configured. See 'git mergetool --tool-help' or 'git help config' for more details. @@ -327,7 +347,7 @@ unavoidable consequence of distributed development. Fortunately, resolving them is common and easy with Git. As a hypothetical example, consider the following code snippet: -.. CODE-BLOCK:: python +.. code-block:: python def fibonacci(i): """ @@ -338,7 +358,7 @@ consider the following code snippet: This is clearly wrong. Two developers, namely Alice and Bob, decide to fix it. Bob corrected the seed values: -.. CODE-BLOCK:: python +.. code-block:: python def fibonacci(i): """ @@ -348,10 +368,12 @@ fix it. Bob corrected the seed values: return fibonacci(i-1) * fibonacci(i-2) return [0, 1][i] -and turned those changes into a new commit:: +and turned those changes into a new commit + +.. code-block:: console - [bob@laptop sage]$ git add fibonacci.py - [bob@laptop sage]$ git commit -m 'return correct seed values' + $ git add fibonacci.py + $ git commit -m 'return correct seed values' He made his changes a PR to the GitHub Sage repo and got it merged to the ``develop`` branch. His ``fibonacci`` function is not yet perfect but is @@ -360,7 +382,7 @@ certainly better than the original. Meanwhile, Alice changed the multiplication to an addition since that is the correct recursion formula: -.. CODE-BLOCK:: python +.. code-block:: python def fibonacci(i): """ @@ -368,12 +390,14 @@ correct recursion formula: """ return fibonacci(i-1) + fibonacci(i-2) -and merged her branch with the latest ``develop`` branch fetched from the GitHub Sage repo:: +and merged her branch with the latest ``develop`` branch fetched from the GitHub Sage repo - [alice@home sage]$ git add fibonacci.py - [alice@home sage]$ git commit -m 'corrected recursion formula, must be + instead of *' - [alice@home sage]$ git fetch upstream develop:develop - [alice@home sage]$ git merge develop +.. code-block:: console + + $ git add fibonacci.py + $ git commit -m 'corrected recursion formula, must be + instead of *' + $ git fetch upstream develop:develop + $ git merge develop ... CONFLICT (content): Merge conflict in fibonacci.py Automatic merge failed; fix conflicts and then commit the result. @@ -382,7 +406,7 @@ The file now looks like this: .. skip # doctester confuses >>> with input marker -.. CODE-BLOCK:: python +.. code-block:: python def fibonacci(i): """ @@ -405,7 +429,7 @@ recent common parent of both. It is now Alice's job to resolve the conflict by reconciling their changes, for example by editing the file. Her result is: -.. CODE-BLOCK:: python +.. code-block:: python def fibonacci(i): """ @@ -415,21 +439,25 @@ changes, for example by editing the file. Her result is: return fibonacci(i-1) + fibonacci(i-2) return [0, 1][i] -And then upload both her original change *and* her merge commit to the GitHub Sage repo:: +And then upload both her original change *and* her merge commit to the GitHub Sage repo + +.. code-block:: console + + $ git add fibonacci.py + $ git commit -m "merged Bob's changes with mine" - [alice@laptop sage]$ git add fibonacci.py - [alice@laptop sage]$ git commit -m "merged Bob's changes with mine" +The resulting commit graph now has a loop -The resulting commit graph now has a loop:: +.. code-block:: console - [alice@laptop sage]$ git log --graph --oneline + $ git log --graph --oneline * 6316447 merged Bob's changes with mine |\ | * 41675df corrected recursion formula, must be + instead of * * | 14ae1d3 return correct seed values |/ * 14afe53 initial commit - [alice@laptop sage]$ git push origin + $ git push origin This time, there is no merge conflict since Alice's branch already merged the ``develop`` branch. diff --git a/src/doc/en/developer/git_setup.rst b/src/doc/en/developer/git_setup.rst index e89900262af..2dde4f57657 100644 --- a/src/doc/en/developer/git_setup.rst +++ b/src/doc/en/developer/git_setup.rst @@ -50,7 +50,7 @@ Assuming your name ``alice`` and email address ``alice@wonderland.com``, This will write the settings into your Git configuration file ``~/.gitconfig`` with your name and email: -.. CODE-BLOCK:: text +.. code-block:: text [user] name = Alice Adventure diff --git a/src/doc/en/developer/github.rst b/src/doc/en/developer/github.rst index fabcbc03b6b..51def999e98 100644 --- a/src/doc/en/developer/github.rst +++ b/src/doc/en/developer/github.rst @@ -43,9 +43,11 @@ Configuration ------------- You have to authenticate to your GitHub account to allow ``gh`` command to -interact with GitHub. Typically the authorization proceeds as follows:: +interact with GitHub. Typically the authorization proceeds as follows - [alice@localhost sage]$ gh auth login +.. code-block:: console + + $ gh auth login ? What is your preferred protocol for Git operations? HTTPS ? Authenticate Git with your GitHub credentials? Yes ? How would you like to authenticate GitHub CLI? Login with a web browser @@ -61,13 +63,17 @@ where a web browser is used to enter credentials. You can also use an authentication token instead, in which case you must first generate `a Personal Access Token here `_. -Next set the default repo for the ``gh`` command:: +Next set the default repo for the ``gh`` command + +.. code-block:: console + + $ gh repo set-default sagemath/sage - [alice@localhost sage]$ gh repo set-default sagemath/sage +and check -and check:: +.. code-block:: console - [alice@localhost sage]$ gh repo view + $ gh repo view sagemath/sage ... @@ -78,9 +84,11 @@ which will show the default repo along with its readme, which is quite long. ``gh`` is extendable; e.g. a useful extension to ``gh`` allows testing of Sage's GitHub Actions locally, using Docker. It is called ``act`` and can be -installed by running:: +installed by running - [alice@localhost sage]$ gh extension install https://github.com/nektos/gh-act +.. code-block:: console + + $ gh extension install https://github.com/nektos/gh-act Append ``--force`` flag to the command above to force an upgrade of the extension. More details on configuring and using ``gh act`` are in :ref:`chapter-portability_testing`. @@ -127,106 +135,108 @@ your fork .. tab:: By HTTPS protocol - :: - - [alice@localhost ~]$ git clone https://github.com/alice/sage.git - Cloning into 'sage'... - remote: Enumerating objects: 914565, done. - remote: Counting objects: 100% (2738/2738), done. - remote: Compressing objects: 100% (855/855), done. - remote: Total 914565 (delta 1950), reused 2493 (delta 1875), pack-reused 911827 - Receiving objects: 100% (914565/914565), 331.09 MiB | 11.22 MiB/s, done. - Resolving deltas: 100% (725438/725438), done. - Updating files: 100% (9936/9936), done. - [alice@localhost ~]$ cd sage - [alice@localhost sage]$ git remote -v - origin https://github.com/alice/sage.git (fetch) - origin https://github.com/alice/sage.git (push) + .. code-block:: console + + $ git clone https://github.com/alice/sage.git + Cloning into 'sage'... + remote: Enumerating objects: 914565, done. + remote: Counting objects: 100% (2738/2738), done. + remote: Compressing objects: 100% (855/855), done. + remote: Total 914565 (delta 1950), reused 2493 (delta 1875), pack-reused 911827 + Receiving objects: 100% (914565/914565), 331.09 MiB | 11.22 MiB/s, done. + Resolving deltas: 100% (725438/725438), done. + Updating files: 100% (9936/9936), done. + $ cd sage + $ git remote -v + origin https://github.com/alice/sage.git (fetch) + origin https://github.com/alice/sage.git (push) .. tab:: By SSH protocol - :: + .. code-block:: console - [alice@localhost ~]$ git clone git@github.com:alice/sage.git - Cloning into 'sage'... - remote: Enumerating objects: 914565, done. - remote: Counting objects: 100% (2738/2738), done. - remote: Compressing objects: 100% (855/855), done. - remote: Total 914565 (delta 1950), reused 2493 (delta 1875), pack-reused 911827 - Receiving objects: 100% (914565/914565), 331.09 MiB | 11.22 MiB/s, done. - Resolving deltas: 100% (725438/725438), done. - Updating files: 100% (9936/9936), done. - [alice@localhost ~]$ cd sage - [alice@localhost sage]$ git remote -v - origin git@github.com:alice/sage.git (fetch) - origin git@github.com:alice/sage.git (push) + $ git clone git@github.com:alice/sage.git + Cloning into 'sage'... + remote: Enumerating objects: 914565, done. + remote: Counting objects: 100% (2738/2738), done. + remote: Compressing objects: 100% (855/855), done. + remote: Total 914565 (delta 1950), reused 2493 (delta 1875), pack-reused 911827 + Receiving objects: 100% (914565/914565), 331.09 MiB | 11.22 MiB/s, done. + Resolving deltas: 100% (725438/725438), done. + Updating files: 100% (9936/9936), done. + $ cd sage + $ git remote -v + origin git@github.com:alice/sage.git (fetch) + origin git@github.com:alice/sage.git (push) If you already have a local Git repo and only want to link your fork as ``origin`` remote, then do: .. tab:: By HTTPS protocol - :: - - [alice@localhost sage]$ git remote add origin https://github.com/alice/sage.git - [alice@localhost sage]$ git remote -v - origin https://github.com/alice/sage.git (fetch) - origin https://github.com/alice/sage.git (push) - [alice@localhost sage]$ git fetch origin - remote: Enumerating objects: 1136, done. - remote: Counting objects: 100% (1084/1084), done. - remote: Compressing objects: 100% (308/308), done. - remote: Total 1136 (delta 825), reused 982 (delta 776), pack-reused 52 - Receiving objects: 100% (1136/1136), 2.62 MiB | 5.30 MiB/s, done. - Resolving deltas: 100% (838/838), completed with 145 local objects. - From https://github.com/alice/sage - * [new branch] develop -> origin/develop + .. code-block:: console + + $ git remote add origin https://github.com/alice/sage.git + $ git remote -v + origin https://github.com/alice/sage.git (fetch) + origin https://github.com/alice/sage.git (push) + $ git fetch origin + remote: Enumerating objects: 1136, done. + remote: Counting objects: 100% (1084/1084), done. + remote: Compressing objects: 100% (308/308), done. + remote: Total 1136 (delta 825), reused 982 (delta 776), pack-reused 52 + Receiving objects: 100% (1136/1136), 2.62 MiB | 5.30 MiB/s, done. + Resolving deltas: 100% (838/838), completed with 145 local objects. + From https://github.com/alice/sage + * [new branch] develop -> origin/develop .. tab:: By SSH protocol - :: - - [alice@localhost sage]$ git remote add origin git@github.com:alice/sage.git - [alice@localhost sage]$ git remote -v - origin git@github.com:alice/sage.git (fetch) - origin git@github.com:alice/sage.git (push) - [alice@localhost sage]$ git fetch origin - remote: Enumerating objects: 1136, done. - remote: Counting objects: 100% (1084/1084), done. - remote: Compressing objects: 100% (308/308), done. - remote: Total 1136 (delta 825), reused 982 (delta 776), pack-reused 52 - Receiving objects: 100% (1136/1136), 2.62 MiB | 5.30 MiB/s, done. - Resolving deltas: 100% (838/838), completed with 145 local objects. - From git@github.com:alice/sage - * [new branch] develop -> origin/develop + .. code-block:: console + + $ git remote add origin git@github.com:alice/sage.git + $ git remote -v + origin git@github.com:alice/sage.git (fetch) + origin git@github.com:alice/sage.git (push) + $ git fetch origin + remote: Enumerating objects: 1136, done. + remote: Counting objects: 100% (1084/1084), done. + remote: Compressing objects: 100% (308/308), done. + remote: Total 1136 (delta 825), reused 982 (delta 776), pack-reused 52 + Receiving objects: 100% (1136/1136), 2.62 MiB | 5.30 MiB/s, done. + Resolving deltas: 100% (838/838), completed with 145 local objects. + From git@github.com:alice/sage + * [new branch] develop -> origin/develop You also add the Sage repo ``sagemath/sage`` as your remote ``upstream``: .. tab:: By HTTPS protocol - :: + .. code-block:: console - [alice@localhost sage]$ git remote add upstream https://github.com/sagemath/sage.git - [alice@localhost sage]$ git remote -v - origin https://github.com/alice/sage.git (fetch) - origin https://github.com/alice/sage.git (push) - upstream https://github.com/sagemath/sage.git (fetch) - upstream https://github.com/sagemath/sage.git (push) + $ git remote add upstream https://github.com/sagemath/sage.git + $ git remote -v + origin https://github.com/alice/sage.git (fetch) + origin https://github.com/alice/sage.git (push) + upstream https://github.com/sagemath/sage.git (fetch) + upstream https://github.com/sagemath/sage.git (push) .. tab:: By SSH protocol - :: + .. code-block:: console + + $ git remote add upstream git@github.com:sagemath/sage.git + $ git remote -v + origin git@github.com:alice/sage.git (fetch) + origin git@github.com:alice/sage.git (push) + upstream git@github.com:sagemath/sage.git (fetch) + upstream git@github.com:sagemath/sage.git (push) - [alice@localhost sage]$ git remote add upstream git@github.com:sagemath/sage.git - [alice@localhost sage]$ git remote -v - origin git@github.com:alice/sage.git (fetch) - origin git@github.com:alice/sage.git (push) - upstream git@github.com:sagemath/sage.git (fetch) - upstream git@github.com:sagemath/sage.git (push) +To prevent accidental pushes to ``upstream`` (instead of ``origin``), you may want to disable it by running -To prevent accidental pushes to ``upstream`` (instead of ``origin``), you may want to disable it by running:: +.. code-block:: console - [alice@localhost sage]$ git remote set-url --push upstream DISABLE + $ git remote set-url --push upstream DISABLE Of course, you can give arbitrary names to your Git remotes, but ``origin`` and ``upstream`` are the established defaults, which will make it easier to use tools @@ -409,7 +419,7 @@ finally fixed. To produce the warning message, use code like the following: -.. CODE-BLOCK:: python +.. code-block:: python from sage.misc.stopgap import stopgap stopgap("This code contains bugs and may be mathematically unreliable.", diff --git a/src/doc/en/developer/packaging.rst b/src/doc/en/developer/packaging.rst index bdfae915090..0ef010050a9 100644 --- a/src/doc/en/developer/packaging.rst +++ b/src/doc/en/developer/packaging.rst @@ -12,9 +12,11 @@ consider incorporating that library into Sage. The current list of available packages are the subdirectories of :sage_root:`build/pkgs/`. The installation of packages is done through a bash script located in :sage_root:`build/bin/sage-spkg`. This script is typically invoked by -giving the command:: +giving the command - [alice@localhost sage]$ ./sage -i ... +.. code-block:: console + + $ ./sage -i ... options can be: @@ -181,7 +183,7 @@ automatically placed in :file:`SAGE_ROOT/upstream` during the installation process). To package it in Sage, we create a subdirectory containing as a minimum the following files: -.. CODE-BLOCK:: text +.. code-block:: text SAGE_ROOT/build/pkgs/foo |-- checksums.ini @@ -193,7 +195,7 @@ a minimum the following files: The following are some additional files which can be added: -.. CODE-BLOCK:: text +.. code-block:: text SAGE_ROOT/build/pkgs/foo |-- distros @@ -256,7 +258,7 @@ In the best case, the upstream project can simply be installed by the usual configure / make / make install steps. In that case, the ``spkg-build.in`` script template would simply consist of: -.. CODE-BLOCK:: bash +.. code-block:: bash cd src sdh_configure @@ -267,7 +269,7 @@ See :ref:`section-sdh-helpers` for more on the helper functions The ``spkg-install.in`` script template would consist of: -.. CODE-BLOCK:: bash +.. code-block:: bash cd src sdh_make_install @@ -280,7 +282,7 @@ If there is any meaningful documentation included but not installed by ``sdh_make_install`` (which calls ``make install``), then you can add something like the following to install it: -.. CODE-BLOCK:: bash +.. code-block:: bash if [ "$SAGE_SPKG_INSTALL_DOCS" = yes ] ; then sdh_make doc @@ -295,7 +297,7 @@ and whether building Slightly modified versions are available: -.. CODE-BLOCK:: bash +.. code-block:: bash # No ``-march=native``. export CFLAGS=$CFLAGS_NON_NATIVE @@ -323,13 +325,13 @@ Likewise for :envvar:`CXXFLAGS`, :envvar:`FCFLAGS`, and :envvar:`F77FLAGS`. code should go in a separate file (e.g. ``spkg-install.py``), and can then be executed from the real ``spkg-install.in`` like: - .. CODE-BLOCK:: text + .. code-block:: text exec sage-bootstrap-python spkg-install.py or - .. CODE-BLOCK:: text + .. code-block:: text exec python3 spkg-install.py @@ -399,7 +401,7 @@ begin with ``sdh_``, which stands for "Sage-distribution helper". the last command if it was non-zero, or with 1 otherwise, and print an error message. This is typically used like: - .. CODE-BLOCK:: bash + .. code-block:: bash command || sdh_die "Command failed" @@ -407,7 +409,7 @@ begin with ``sdh_``, which stands for "Sage-distribution helper". from stdin. In particular this is useful in conjunction with a heredoc to write multi-line error messages: - .. CODE-BLOCK:: bash + .. code-block:: bash command || sdh_die << _EOF_ Command failed. @@ -573,7 +575,7 @@ has some sort of test suite that can be run with the standard ``make check`` target. In that case, the ``spkg-check.in`` script template would simply contain: -.. CODE-BLOCK:: bash +.. code-block:: bash cd src $MAKE check @@ -592,7 +594,7 @@ as ``pip`` and ``setuptools`` are available at the time of building the package. The best way to install a ``normal`` Python-based package is to use ``pip``, in which case the ``spkg-install.in`` script template might just consist of -.. CODE-BLOCK:: bash +.. code-block:: bash cd src && sdh_pip_install . @@ -605,7 +607,7 @@ than just ``python``. The paths are set by the Sage build system so that this runs the correct version of Python. For example, the ``scipy`` ``spkg-check.in`` file contains the line -.. CODE-BLOCK:: bash +.. code-block:: bash exec python3 spkg-check.py @@ -645,7 +647,7 @@ warranted or why we wish to include or reject certain versions. For example: -.. CODE-BLOCK:: bash +.. code-block:: console $ cat build/pkgs/sphinx/package-version.txt 3.1.2.p0 @@ -655,7 +657,7 @@ For example: The comments may include links to GitHub Issues/PRs, as in the following example: -.. CODE-BLOCK:: bash +.. code-block:: console $ cat build/pkgs/packaging/version_requirements.txt packaging >=18.0 @@ -758,7 +760,7 @@ The SPKG.rst file The ``SPKG.rst`` file should follow this pattern: -.. CODE-BLOCK:: text +.. code-block:: text PACKAGE_NAME: One line description ================================== @@ -809,7 +811,7 @@ Many packages depend on other packages. Consider for example the PARI, NTL and FLINT. So the following is the ``dependencies`` file for ``eclib``: -.. CODE-BLOCK:: text +.. code-block:: text pari ntl flint @@ -821,7 +823,7 @@ For Python packages, common dependencies include ``pip``, these, use ``$(PYTHON_TOOLCHAIN)`` instead. For example, here is the ``dependencies`` file for ``configparser``: -.. CODE-BLOCK:: text +.. code-block:: text $(PYTHON) | $(PYTHON_TOOLCHAIN) @@ -829,7 +831,7 @@ these, use ``$(PYTHON_TOOLCHAIN)`` instead. For example, here is the If there are no dependencies, you can use -.. CODE-BLOCK:: text +.. code-block:: text # no dependencies @@ -840,7 +842,7 @@ There are actually two kinds of dependencies: there are normal dependencies and order-only dependencies, which are weaker. The syntax for the ``dependencies`` file is -.. CODE-BLOCK:: text +.. code-block:: text normal dependencies | order-only dependencies @@ -870,9 +872,11 @@ a dependency if they are configured to be installed. These dependencies should be declared in a separate file ``dependencies_optional``. In order to check that the dependencies of your package are likely -correct, the following command should work without errors:: +correct, the following command should work without errors + +.. code-block:: console - [alice@localhost sage]$ make distclean && make PACKAGE_NAME + $ make distclean && make PACKAGE_NAME Finally, note that standard packages should only depend on standard packages and optional packages should only depend on standard or @@ -976,7 +980,7 @@ upstream tarball (without the actual version) and its checksums. So if upstream is ``$SAGE_ROOT/upstream/FoO-1.3.tar.gz``, create a new file ``$SAGE_ROOT/build/pkgs/foo/checksums.ini`` containing only: -.. CODE-BLOCK:: bash +.. code-block:: bash tarball=FoO-VERSION.tar.gz @@ -1007,7 +1011,7 @@ to refer to the dot-separated components of a version by ``VERSION_MAJOR``, For Python packages available from PyPI, you should use an ``upstream_url`` from ``files.pythonhosted.org``, which follows the format -.. CODE-BLOCK:: bash +.. code-block:: bash upstream_url=https://files.pythonhosted.org/packages/source/m/matplotlib/matplotlib-VERSION.tar.gz @@ -1032,12 +1036,14 @@ Creating packages ----------------- Assuming that you have downloaded -``$SAGE_ROOT/upstream/FoO-1.3.tar.gz``, you can use:: +``$SAGE_ROOT/upstream/FoO-1.3.tar.gz``, you can use - [alice@localhost sage]$ ./sage --package create foo \ - --version 1.3 \ - --tarball FoO-VERSION.tar.gz \ - --type experimental +.. code-block:: console + + $ ./sage --package create foo \ + --version 1.3 \ + --tarball FoO-VERSION.tar.gz \ + --type experimental to create ``$SAGE_ROOT/build/pkgs/foo/package-version.txt``, ``checksums.ini``, and ``type`` in one step. @@ -1047,15 +1053,19 @@ the additional argument ``--upstream-url``. This command will also set the ``upstream_url`` field in ``checksums.ini`` described above. For Python packages available from PyPI, use a PURL (Package URL, -see `PEP 725 `_):: +see `PEP 725 `_) + +.. code-block:: console - [alice@localhost sage]$ ./sage --package create pkg:pypi/scikit-spatial \ - --type optional + $ ./sage --package create pkg:pypi/scikit-spatial \ + --type optional -An equivalent command uses the SPKG name of the new package:: +An equivalent command uses the SPKG name of the new package - [alice@localhost sage]$ ./sage --package create scikit_spatial --pypi \ - --type optional +.. code-block:: console + + $ ./sage --package create scikit_spatial --pypi \ + --type optional Either of these two commands automatically downloads the most recent version from PyPI and also obtains most of the necessary information by querying PyPI. @@ -1076,17 +1086,21 @@ in the file ``version_requirements.txt``. (Make sure that the version in ``package-version.txt`` falls within this acceptable version range!) To create a ``normal`` package instead of a ``wheel`` package (for example, when the -package requires patching), you can use:: +package requires patching), you can use + +.. code-block:: console - [alice@localhost sage]$ ./sage --package create pkg:pypi/scikit-spatial \ - --source normal \ - --type optional + $ ./sage --package create pkg:pypi/scikit-spatial \ + --source normal \ + --type optional -To create a ``pip`` package rather than a ``normal`` or ``wheel`` package, you can use:: +To create a ``pip`` package rather than a ``normal`` or ``wheel`` package, you can use - [alice@localhost sage]$ ./sage --package create pkg:pypi/scikit-spatial \ - --source pip \ - --type optional +.. code-block:: console + + $ ./sage --package create pkg:pypi/scikit-spatial \ + --source pip \ + --type optional When the package already exists, ``sage --package create`` overwrites it. @@ -1095,16 +1109,20 @@ Updating packages to a new version ---------------------------------- A package that has the ``upstream_url`` information can be updated by -simply typing:: +simply typing + +.. code-block:: console - [alice@localhost sage]$ ./sage --package update openblas 0.3.79 + $ ./sage --package update openblas 0.3.79 which will automatically download the archive and update the information in ``build/pkgs/openblas/``. -For Python packages available from PyPI, there is another shortcut:: +For Python packages available from PyPI, there is another shortcut - [alice@localhost sage]$ ./sage --package update-latest pkg:pypi/matplotlib +.. code-block:: console + + $ ./sage --package update-latest pkg:pypi/matplotlib Updating matplotlib: 3.3.0 -> 3.3.1 Downloading tarball to ...matplotlib-3.3.1.tar.bz2 [...............................................................] @@ -1119,9 +1137,11 @@ If you pass the switch ``--commit``, the script will run ``git commit`` for you. If you prefer to update a package ``foo`` by making manual -changes to the files in ``build/pkgs/foo``, you will need to run:: +changes to the files in ``build/pkgs/foo``, you will need to run + +.. code-block:: console - [alice@localhost sage]$ ./sage --package fix-checksum foo + $ ./sage --package fix-checksum foo which will modify the ``checksums.ini`` file with the correct checksums. @@ -1132,9 +1152,11 @@ Obtaining package metrics The command ``sage --package metrics`` computes machine-readable aggregated metrics for all packages in the Sage distribution or a -given list of packages:: +given list of packages - [alice@localhost sage]$ ./sage --package metrics +.. code-block:: console + + $ ./sage --package metrics has_file_distros_arch_txt=181 has_file_distros_conda_txt=289 has_file_distros_debian_txt=172 @@ -1206,22 +1228,30 @@ At this stage you have a new tarball that is not yet distributed with Sage (``FoO-1.3.tar.gz`` in the example of section :ref:`section-directory-structure`). -Now you can install the package using:: +Now you can install the package using + +.. code-block:: console - [alice@localhost sage]$ ./sage -i package_name + $ ./sage -i package_name -or:: +or - [alice@localhost sage]$ ./sage -f package_name +.. code-block:: console + + $ ./sage -f package_name to force a reinstallation. If your package contains a ``spkg-check`` -script (see :ref:`section-spkg-check`) it can be run with:: +script (see :ref:`section-spkg-check`) it can be run with + +.. code-block:: console + + $ ./sage -i -c package_name - [alice@localhost sage]$ ./sage -i -c package_name +or -or:: +.. code-block:: console - [alice@localhost sage]$ ./sage -f -c package_name + $ ./sage -f -c package_name If all went fine, open a PR with the code under :sage_root:`build/pkgs`. @@ -1259,7 +1289,7 @@ When to patch, when to repackage, when to autoconfiscate - Sometimes it may seem as if you need to patch a (hand-written) ``Makefile`` because it "hard-codes" some paths or compiler flags: - .. CODE-BLOCK:: diff + .. code-block:: diff --- a/Makefile +++ b/Makefile @@ -1276,7 +1306,7 @@ When to patch, when to repackage, when to autoconfiscate Don't use patching for that. Makefile variables can be overridden from the command-line. Just use the following in ``spkg-install``: - .. CODE-BLOCK:: bash + .. code-block:: console $(MAKE) DESTDIR="$SAGE_ROOT/local" @@ -1343,7 +1373,7 @@ must have only one "prefix" level in the paths (that is, only one path level above the root of the upstream sources being patched). So a typical patch file should look like this: -.. CODE-BLOCK:: diff +.. code-block:: diff Add autodoc_builtin_argspec config option @@ -1371,7 +1401,7 @@ a specifically platform), you can place those patches in a subdirectory of ``patches/`` and apply them manually using the ``sage-apply-patches`` script. For example, considering the layout: -.. CODE-BLOCK:: text +.. code-block:: text SAGE_ROOT/build/pkgs/foo |-- patches @@ -1385,7 +1415,7 @@ upstream sources in ``src/`` before running ``spkg-install``. To conditionally apply the patch for Solaris the ``spkg-install`` should contain a section like this: -.. CODE-BLOCK:: bash +.. code-block:: bash if [ $UNAME == "SunOS" ]; then sage-apply-patches -d solaris @@ -1417,7 +1447,7 @@ We recommend the following workflow for maintaining a set of patches. - Generate the patches against the ``upstream`` branch: - .. CODE-BLOCK:: bash + .. code-block:: bash rm -Rf SAGE_ROOT/build/pkgs/PACKAGE/patches mkdir SAGE_ROOT/build/pkgs/PACKAGE/patches @@ -1431,7 +1461,7 @@ We recommend the following workflow for maintaining a set of patches. into ``upstream``, then create a new branch and rebase it on top of the updated upstream: - .. CODE-BLOCK:: bash + .. code-block:: bash git checkout sage_package_OLDVERSION git checkout -b sage_package_NEWVERSION diff --git a/src/doc/en/developer/packaging_sage_library.rst b/src/doc/en/developer/packaging_sage_library.rst index a25261f0936..e4541784672 100644 --- a/src/doc/en/developer/packaging_sage_library.rst +++ b/src/doc/en/developer/packaging_sage_library.rst @@ -141,15 +141,19 @@ The source directory of a distribution package, such as The manifest should be kept in sync with the directives of the form ``# sage_setup: distribution = sagemath-polyhedra`` at the top of source files. Sage provides a tool ``sage --fixdistributions`` - that assists with this task. For example:: + that assists with this task. For example - $ ./sage --fixdistributions --set sagemath-polyhedra \ - src/sage/geometry/polyhedron/base*.py + .. code-block:: console - adds or updates the directives in the specified files; and:: + $ ./sage --fixdistributions --set sagemath-polyhedra \ + src/sage/geometry/polyhedron/base*.py - $ ./sage --fixdistributions --add sagemath-polyhedra \ - src/sage/geometry/polyhedron + adds or updates the directives in the specified files; and + + .. code-block:: console + + $ ./sage --fixdistributions --add sagemath-polyhedra \ + src/sage/geometry/polyhedron adds the directive to all files in the given directory that do not include a directive yet. @@ -158,13 +162,17 @@ The source directory of a distribution package, such as ``make pypi-wheels``) or at least an sdist has been built (for example, by the command ``make sagemath_polyhedra-sdist``), the distribution directives in all files in the source distribution - can be updated using the switch ``--from--egg-info``:: + can be updated using the switch ``--from--egg-info`` + + .. code-block:: console - $ ./sage --fixdistributions --set sagemath-polyhedra --from-egg-info + $ ./sage --fixdistributions --set sagemath-polyhedra --from-egg-info - To take care of all distributions, use:: + To take care of all distributions, use - $ ./sage --fixdistributions --set all --from-egg-info + .. code-block:: console + + $ ./sage --fixdistributions --set all --from-egg-info - `pyproject.toml `_, `setup.cfg `_, @@ -415,14 +423,16 @@ case it will be up to the user to install the distribution enabling this optional functionality. As an example, let us consider designing a distribution that centers -around the package :mod:`sage.coding`. First, let's see if it uses symbolics:: +around the package :mod:`sage.coding`. First, let's see if it uses symbolics + +.. code-block:: console - (9.5.beta6) $ git grep -E 'sage[.](symbolic|functions|calculus)' src/sage/coding - src/sage/coding/code_bounds.py: from sage.functions.other import ceil - ... - src/sage/coding/grs_code.py:from sage.symbolic.ring import SR - ... - src/sage/coding/guruswami_sudan/utils.py:from sage.functions.other import floor + $ git grep -E 'sage[.](symbolic|functions|calculus)' src/sage/coding + src/sage/coding/code_bounds.py: from sage.functions.other import ceil + ... + src/sage/coding/grs_code.py:from sage.symbolic.ring import SR + ... + src/sage/coding/guruswami_sudan/utils.py:from sage.functions.other import floor Apparently it does not in a very substantial way: @@ -613,32 +623,36 @@ distribution to be tested (and its Python dependencies). Let's try it out first with the entire Sage library, represented by the distribution **sagemath-standard**. Note that after Sage has been built normally, a set of wheels for most installed Python distribution -packages is available in ``SAGE_VENV/var/lib/sage/wheels/``:: - - $ ls venv/var/lib/sage/wheels - Babel-2.9.1-py2.py3-none-any.whl - Cython-0.29.24-cp39-cp39-macosx_11_0_x86_64.whl - Jinja2-2.11.2-py2.py3-none-any.whl - ... - scipy-1.7.2-cp39-cp39-macosx_11_0_x86_64.whl - setuptools-58.2.0-py3-none-any.whl - ... - wheel-0.37.0-py2.py3-none-any.whl - widgetsnbextension-3.5.1-py2.py3-none-any.whl - zipp-3.5.0-py3-none-any.whl +packages is available in ``SAGE_VENV/var/lib/sage/wheels/`` + +.. code-block:: console + + $ ls venv/var/lib/sage/wheels + Babel-2.9.1-py2.py3-none-any.whl + Cython-0.29.24-cp39-cp39-macosx_11_0_x86_64.whl + Jinja2-2.11.2-py2.py3-none-any.whl + ... + scipy-1.7.2-cp39-cp39-macosx_11_0_x86_64.whl + setuptools-58.2.0-py3-none-any.whl + ... + wheel-0.37.0-py2.py3-none-any.whl + widgetsnbextension-3.5.1-py2.py3-none-any.whl + zipp-3.5.0-py3-none-any.whl However, in a build of Sage with the default configuration ``configure --enable-editable``, there will be no wheels for the distributions ``sage_*`` and ``sagemath-*``. -To create these wheels, use the command ``make wheels``:: +To create these wheels, use the command ``make wheels`` + +.. code-block:: console - $ make wheels - ... - $ ls venv/var/lib/sage/wheels/sage* - ... - sage_conf-10.0b2-py3-none-any.whl - ... + $ make wheels + ... + $ ls venv/var/lib/sage/wheels/sage* + ... + sage_conf-10.0b2-py3-none-any.whl + ... (You can also use ``./configure --enable-wheels`` to ensure that these wheels are always available and up to date.) @@ -652,21 +666,27 @@ disposable virtual environments for testing. Every distribution in Following the comments in the file :sage_root:`pkgs/sagemath-standard/tox.ini`, we can try the following -command:: +command - $ ./bootstrap && ./sage -sh -c '(cd pkgs/sagemath-standard && SAGE_NUM_THREADS=16 tox -v -v -v -e sagepython-sagewheels-nopypi)' +.. code-block:: console + + $ ./bootstrap && ./sage -sh -c '(cd pkgs/sagemath-standard && SAGE_NUM_THREADS=16 tox -v -v -v -e sagepython-sagewheels-nopypi)' This command does not make any changes to the normal installation of Sage. The virtual environment is created in a subdirectory of :file:`SAGE_ROOT/pkgs/sagemath-standard/.tox/`. After the command finishes, we can start the separate installation of the Sage library -in its virtual environment:: +in its virtual environment + +.. code-block:: console + + $ pkgs/sagemath-standard/.tox/sagepython-sagewheels-nopypi/bin/sage - $ pkgs/sagemath-standard/.tox/sagepython-sagewheels-nopypi/bin/sage +We can also run parts of the testsuite -We can also run parts of the testsuite:: +.. code-block:: console - $ pkgs/sagemath-standard/.tox/sagepython-sagewheels-nopypi/bin/sage -tp 4 src/sage/graphs/ + $ pkgs/sagemath-standard/.tox/sagepython-sagewheels-nopypi/bin/sage -tp 4 src/sage/graphs/ The whole ``.tox`` directory can be safely deleted at any time. @@ -677,17 +697,21 @@ everything that is currently in the standard Sage library, i.e., without depending on optional packages, but without the packages :mod:`sage.symbolic`, :mod:`sage.calculus`, etc. -Again we can run the test with ``tox`` in a separate virtual environment:: +Again we can run the test with ``tox`` in a separate virtual environment - $ ./bootstrap && make wheels && ./sage -sh -c '(cd pkgs/sagemath-standard-no-symbolics && SAGE_NUM_THREADS=16 tox -v -v -v -e sagepython-sagewheels-nopypi-norequirements)' +.. code-block:: console + + $ ./bootstrap && make wheels && ./sage -sh -c '(cd pkgs/sagemath-standard-no-symbolics && SAGE_NUM_THREADS=16 tox -v -v -v -e sagepython-sagewheels-nopypi-norequirements)' Some small distributions, for example the ones providing the two lowest levels, `sagemath-objects `_ and `sagemath-categories `_ (from :issue:`29865`), can be installed and tested -without relying on the wheels from the Sage build:: +without relying on the wheels from the Sage build + +.. code-block:: console - $ ./bootstrap && ./sage -sh -c '(cd pkgs/sagemath-objects && SAGE_NUM_THREADS=16 tox -v -v -v -e sagepython)' + $ ./bootstrap && ./sage -sh -c '(cd pkgs/sagemath-objects && SAGE_NUM_THREADS=16 tox -v -v -v -e sagepython)' This command finds the declared build-time and run-time dependencies on PyPI, either as source tarballs or as prebuilt wheels, and builds diff --git a/src/doc/en/developer/portability_testing.rst b/src/doc/en/developer/portability_testing.rst index 237165a5ea5..16a3e6dbc80 100644 --- a/src/doc/en/developer/portability_testing.rst +++ b/src/doc/en/developer/portability_testing.rst @@ -87,10 +87,12 @@ All major Linux distributions provide ready-to-use Docker images, which are published via `Docker Hub `_ or other container registries. For example, to run the current stable (LTS) version of Ubuntu -interactively, you can use the shell command:: +interactively, you can use the shell command - [mkoeppe@sage sage]$ docker run -it ubuntu:latest - root@9f3398da43c2:/# +.. code-block:: console + + $ docker run -it ubuntu:latest + root@9f3398da43c2:/# Here ``ubuntu`` is referred to as the "image (name)" and ``latest`` as the "tag". Other releases of Ubuntu are available under different @@ -98,46 +100,54 @@ tags, such as ``xenial`` or ``devel``. The above command drops you in a root shell on the container:: - root@9f3398da43c2:/# uname -a - Linux 9f3398da43c2 4.19.76-linuxkit #1 SMP Thu Oct 17 19:31:58 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux - root@9f3398da43c2:/# df -h - Filesystem Size Used Avail Use% Mounted on - overlay 181G 116G 56G 68% / - tmpfs 64M 0 64M 0% /dev - tmpfs 2.7G 0 2.7G 0% /sys/fs/cgroup - shm 64M 0 64M 0% /dev/shm - /dev/sda1 181G 116G 56G 68% /etc/hosts - tmpfs 2.7G 0 2.7G 0% /proc/acpi - tmpfs 2.7G 0 2.7G 0% /sys/firmware + root@9f3398da43c2:/# uname -a + Linux 9f3398da43c2 4.19.76-linuxkit #1 SMP Thu Oct 17 19:31:58 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux + root@9f3398da43c2:/# df -h + Filesystem Size Used Avail Use% Mounted on + overlay 181G 116G 56G 68% / + tmpfs 64M 0 64M 0% /dev + tmpfs 2.7G 0 2.7G 0% /sys/fs/cgroup + shm 64M 0 64M 0% /dev/shm + /dev/sda1 181G 116G 56G 68% /etc/hosts + tmpfs 2.7G 0 2.7G 0% /proc/acpi + tmpfs 2.7G 0 2.7G 0% /sys/firmware + +Exiting the shell terminates the container -Exiting the shell terminates the container:: +.. code-block:: console - root@9f3398da43c2:/# ^D - [mkoeppe@sage sage]$ + root@9f3398da43c2:/# ^D + $ Let us work with a distclean Sage source tree. If you are using git, a good way to get one (without losing a precious installation in -``SAGE_LOCAL``) is by creating a new worktree:: +``SAGE_LOCAL``) is by creating a new worktree - [mkoeppe@sage sage] git worktree add worktree-ubuntu-latest - [mkoeppe@sage sage] cd worktree-ubuntu-latest - [mkoeppe@sage worktree-ubuntu-latest] ls - COPYING.txt ... Makefile ... configure.ac ... src tox.ini +.. code-block:: console -This is not bootstrapped (``configure`` is missing), so let's bootstrap it:: + $ git worktree add worktree-ubuntu-latest + $ cd worktree-ubuntu-latest + $ ls + COPYING.txt ... Makefile ... configure.ac ... src tox.ini - [mkoeppe@sage worktree-ubuntu-latest] make configure - ... +This is not bootstrapped (``configure`` is missing), so let's bootstrap it + +.. code-block:: console + + $ make configure + ... We can start a container again with same image, ``ubuntu:latest``, but -this time let's mount the current directory into it:: +this time let's mount the current directory into it + +.. code-block:: console - [mkoeppe@sage worktree-ubuntu-latest]$ docker run -it --mount type=bind,source=$(pwd),target=/sage ubuntu:latest - root@39d693b2a75d:/# mount | grep sage - osxfs on /sage type fuse.osxfs (rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=1048576) - root@39d693b2a75d:/# cd sage - root@39d693b2a75d:/sage# ls - COPYING.txt ... Makefile ... config configure configure.ac ... src tox.ini + $ docker run -it --mount type=bind,source=$(pwd),target=/sage ubuntu:latest + root@39d693b2a75d:/# mount | grep sage + osxfs on /sage type fuse.osxfs (rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=1048576) + root@39d693b2a75d:/# cd sage + root@39d693b2a75d:/sage# ls + COPYING.txt ... Makefile ... config configure configure.ac ... src tox.ini Typical Docker images provide minimal installations of packages only:: @@ -257,13 +267,15 @@ following:: configure: $ make reconfigure This information comes from Sage's database of equivalent system -packages. For example:: +packages. For example - $ ls build/pkgs/flint/distros/ - alpine.txt fedora.txt gentoo.txt macports.txt opensuse.txt void.txt - conda.txt debian.txt freebsd.txt homebrew.txt nix.txt repology.txt - $ cat build/pkgs/flint/distros/debian.txt - libflint-dev +.. code-block:: console + + $ ls build/pkgs/flint/distros/ + alpine.txt fedora.txt gentoo.txt macports.txt opensuse.txt void.txt + conda.txt debian.txt freebsd.txt homebrew.txt nix.txt repology.txt + $ cat build/pkgs/flint/distros/debian.txt + libflint-dev Note that these package equivalencies are based on a current stable or testing version of the distribution; the packages are not guaranteed @@ -289,27 +301,33 @@ Committing a container to disk ------------------------------ After terminating the container, the following command shows the status -of the container you just exited:: +of the container you just exited + +.. code-block:: console + + root@39d693b2a75d:/sage# ^D + $ docker ps -a | head -n3 + CONTAINER ID IMAGE COMMAND CREATED STATUS + 39d693b2a75d ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 6 seconds ago + 9f3398da43c2 ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 8 minutes ago - root@39d693b2a75d:/sage# ^D - [mkoeppe@sage worktree-ubuntu-latest]$ docker ps -a | head -n3 - CONTAINER ID IMAGE COMMAND CREATED STATUS - 39d693b2a75d ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 6 seconds ago - 9f3398da43c2 ubuntu:latest "/bin/bash" 8 minutes ago Exited (0) 8 minutes ago +We can go back to the container with the command -We can go back to the container with the command:: +.. code-block:: console - [mkoeppe@sage worktree-ubuntu-latest]$ docker start -a -i 39d693b2a75d - root@9f3398da43c2:/# + $ docker start -a -i 39d693b2a75d + root@9f3398da43c2:/# Here, ``39d693b2a75d`` is the container id, which appeared in the shell prompts and in the output of ``docker ps``. -We can create a new image corresponding to its current state:: +We can create a new image corresponding to its current state - root@39d693b2a75d:/# ^D - [mkoeppe@sage worktree-ubuntu-latest]$ docker commit 39d693b2a75d ubuntu-latest-minimal-17 - sha256:4151c5ca4476660f6181cdb13923da8fe44082222b984c377fb4fd6cc05415c1 +.. code-block:: console + + root@39d693b2a75d:/# ^D + $ docker commit 39d693b2a75d ubuntu-latest-minimal-17 + sha256:4151c5ca4476660f6181cdb13923da8fe44082222b984c377fb4fd6cc05415c1 where ``ubuntu-latest-minimal-17`` is an arbitrary symbolic name for the new image. The output of the command is the id of the new image. We can use either @@ -318,17 +336,19 @@ the symbolic name or the id to refer to the new image. We can run the image and get a new container with the same state as the one that we terminated. Again we want to mount our worktree into it; otherwise, because we did not make a copy, the new container will -have no access to the worktree:: +have no access to the worktree + +.. code-block:: console - [mkoeppe@sage worktree-ubuntu-latest]$ docker run -it \ + $ docker run -it \ --mount type=bind,source=$(pwd),target=/sage ubuntu-latest-minimal-17 - root@73987568712c:/# cd sage - root@73987568712c:/sage# command -v gcc - /usr/bin/gcc - root@73987568712c:/sage# command -v bunzip2 - /usr/bin/bunzip2 - root@73987568712c:/sage# ^D - [mkoeppe@sage worktree-ubuntu-latest]$ + root@73987568712c:/# cd sage + root@73987568712c:/sage# command -v gcc + /usr/bin/gcc + root@73987568712c:/sage# command -v bunzip2 + /usr/bin/bunzip2 + root@73987568712c:/sage# ^D + $ The image ``ubuntu-latest-minimal-17`` can be run in as many containers as we want and can also be shared with other users or @@ -348,9 +368,11 @@ Generating dockerfiles ---------------------- Sage also provides a script for generating a ``Dockerfile``, which is -a recipe for automatically building a new image:: +a recipe for automatically building a new image + +.. code-block:: console - [mkoeppe@sage sage]$ .github/workflows/write-dockerfile.sh debian ":standard: :optional:" > Dockerfile + $ .github/workflows/write-dockerfile.sh debian ":standard: :optional:" > Dockerfile (The second argument is passed to ``sage -package list`` to find packages for the listed package types.) @@ -358,13 +380,15 @@ a recipe for automatically building a new image:: The ``Dockerfile`` instructs the command ``docker build`` to build a new Docker image. Let us take a quick look at the generated file; -this is slightly simplified:: +this is slightly simplified - [mkoeppe@sage sage]$ cat Dockerfile - # Automatically generated by write-dockerfile.sh - # the :comments: separate the generated file into sections - # to simplify writing scripts that customize this file - ... +.. code-block:: console + + $ cat Dockerfile + # Automatically generated by write-dockerfile.sh + # the :comments: separate the generated file into sections + # to simplify writing scripts that customize this file + ... First, it instructs ``docker build`` to start from an existing base image...:: @@ -405,12 +429,14 @@ Finally, to build and test...:: RUN make ${USE_MAKEFLAGS} ${TARGETS} You can customize the image build process by passing build arguments to the -command ``docker build``. For example:: +command ``docker build``. For example + +.. code-block:: console - [mkoeppe@sage sage]$ docker build . -f Dockerfile \ - --build-arg BASE_IMAGE=ubuntu:latest \ - --build-arg NUMPROC=4 \ - --build-arg EXTRA_CONFIGURE_ARGS="--with-python=/usr/bin/python3.42" + $ docker build . -f Dockerfile \ + --build-arg BASE_IMAGE=ubuntu:latest \ + --build-arg NUMPROC=4 \ + --build-arg EXTRA_CONFIGURE_ARGS="--with-python=/usr/bin/python3.42" These arguments (and their default values) are defined using ``ARG`` commands in the ``Dockerfile``. @@ -418,43 +444,47 @@ commands in the ``Dockerfile``. The above command will build Sage from scratch and will therefore take quite long. Let us instead just do a partial build, consisting of one small package, by setting the arguments ``TARGETS_PRE`` and -``TARGETS``. We use a silent build (``make V=0``):: - - [mkoeppe@sage sage]$ docker build . -f Dockerfile \ - --build-arg TARGETS_PRE=ratpoints \ - --build-arg TARGETS=ratpoints \ - --build-arg USE_MAKEFLAGS="V=0" - Sending build context to Docker daemon 285MB - Step 1/28 : ARG BASE_IMAGE=ubuntu:latest - ... - Step 2/28 : FROM ${BASE_IMAGE} - ---> 549b9b86cb8d - ... - Step 25/28 : RUN make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE} - ... - make[1]: Entering directory '/sage/build/make' - sage-logger -p 'sage-spkg -y -o ratpoints-2.1.3.p5' '/sage/logs/pkgs/ratpoints-2.1.3.p5.log' - [ratpoints-2.1.3.p5] installing. Log file: /sage/logs/pkgs/ratpoints-2.1.3.p5.log - [ratpoints-2.1.3.p5] successfully installed. - make[1]: Leaving directory '/sage/build/make' - - real 0m18.886s - user 0m1.779s - sys 0m0.314s - Sage build/upgrade complete! - ... - ---> 2d06689d39fa - Successfully built 2d06689d39fa - -We can now start a container using the image id shown in the last step:: - - [mkoeppe@sage sage]$ docker run -it 2d06689d39fa bash - root@fab59e09a641:/sage# ls -l logs/pkgs/ - total 236 - -rw-r--r-- 1 root root 231169 Mar 26 22:07 config.log - -rw-r--r-- 1 root root 6025 Mar 26 22:27 ratpoints-2.1.3.p5.log - root@fab59e09a641:/sage# ls -l local/lib/*rat* - -rw-r--r-- 1 root root 177256 Mar 26 22:27 local/lib/libratpoints.a +``TARGETS``. We use a silent build (``make V=0``) + +.. code-block:: console + + $ docker build . -f Dockerfile \ + --build-arg TARGETS_PRE=ratpoints \ + --build-arg TARGETS=ratpoints \ + --build-arg USE_MAKEFLAGS="V=0" + Sending build context to Docker daemon 285MB + Step 1/28 : ARG BASE_IMAGE=ubuntu:latest + ... + Step 2/28 : FROM ${BASE_IMAGE} + ---> 549b9b86cb8d + ... + Step 25/28 : RUN make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE} + ... + make[1]: Entering directory '/sage/build/make' + sage-logger -p 'sage-spkg -y -o ratpoints-2.1.3.p5' '/sage/logs/pkgs/ratpoints-2.1.3.p5.log' + [ratpoints-2.1.3.p5] installing. Log file: /sage/logs/pkgs/ratpoints-2.1.3.p5.log + [ratpoints-2.1.3.p5] successfully installed. + make[1]: Leaving directory '/sage/build/make' + + real 0m18.886s + user 0m1.779s + sys 0m0.314s + Sage build/upgrade complete! + ... + ---> 2d06689d39fa + Successfully built 2d06689d39fa + +We can now start a container using the image id shown in the last step + +.. code-block:: console + + $docker run -it 2d06689d39fa bash + root@fab59e09a641:/sage# ls -l logs/pkgs/ + total 236 + -rw-r--r-- 1 root root 231169 Mar 26 22:07 config.log + -rw-r--r-- 1 root root 6025 Mar 26 22:27 ratpoints-2.1.3.p5.log + root@fab59e09a641:/sage# ls -l local/lib/*rat* + -rw-r--r-- 1 root root 177256 Mar 26 22:27 local/lib/libratpoints.a You can customize the image build process further by editing the ``Dockerfile``. For example, by default, the generated ``Dockerfile`` @@ -490,115 +520,123 @@ Debugging a portability bug using Docker Let us do another partial build. We choose a package that we suspect might not work on all platforms, ``surf``, which was marked as -"experimental" in 2017:: - - [mkoeppe@sage sage]$ docker build . -f Dockerfile \ - --build-arg BASE_IMAGE=ubuntu:latest \ - --build-arg NUMPROC=4 \ - --build-arg TARGETS_PRE=surf \ - --build-arg TARGETS=surf - Sending build context to Docker daemon 285MB - Step 1/28 : ARG BASE_IMAGE=ubuntu:latest - Step 2/28 : FROM ${BASE_IMAGE} - ---> 549b9b86cb8d - ... - Step 24/28 : ARG TARGETS_PRE="all-sage-local" - ---> Running in 17d0ddb5ad7b - Removing intermediate container 17d0ddb5ad7b - ---> 7b51411520c3 - Step 25/28 : RUN make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE} - ---> Running in 61833bea6a6d - make -j4 build/make/Makefile --stop - ... - [surf-1.0.6-gcc6] Attempting to download package surf-1.0.6-gcc6.tar.gz from mirrors - ... - [surf-1.0.6-gcc6] http://mirrors.mit.edu/sage/spkg/upstream/surf/surf-1.0.6-gcc6.tar.gz - ... - [surf-1.0.6-gcc6] Setting up build directory for surf-1.0.6-gcc6 - ... - [surf-1.0.6-gcc6] /usr/bin/ld: cannot find -lfl - [surf-1.0.6-gcc6] collect2: error: ld returned 1 exit status - [surf-1.0.6-gcc6] Makefile:504: recipe for target 'surf' failed - [surf-1.0.6-gcc6] make[3]: *** [surf] Error 1 - ... - [surf-1.0.6-gcc6] Error installing package surf-1.0.6-gcc6 - ... - Makefile:2088: recipe for target '/sage/local/var/lib/sage/installed/surf-1.0.6-gcc6' failed - make[1]: *** [/sage/local/var/lib/sage/installed/surf-1.0.6-gcc6] Error 1 - make[1]: Target 'surf' not remade because of errors. - make[1]: Leaving directory '/sage/build/make' - ... - Error building Sage. +"experimental" in 2017 + +.. code-block:: console + + $ docker build . -f Dockerfile \ + --build-arg BASE_IMAGE=ubuntu:latest \ + --build-arg NUMPROC=4 \ + --build-arg TARGETS_PRE=surf \ + --build-arg TARGETS=surf + Sending build context to Docker daemon 285MB + Step 1/28 : ARG BASE_IMAGE=ubuntu:latest + Step 2/28 : FROM ${BASE_IMAGE} + ---> 549b9b86cb8d + ... + Step 24/28 : ARG TARGETS_PRE="all-sage-local" + ---> Running in 17d0ddb5ad7b + Removing intermediate container 17d0ddb5ad7b + ---> 7b51411520c3 + Step 25/28 : RUN make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE} + ---> Running in 61833bea6a6d + make -j4 build/make/Makefile --stop + ... + [surf-1.0.6-gcc6] Attempting to download package surf-1.0.6-gcc6.tar.gz from mirrors + ... + [surf-1.0.6-gcc6] http://mirrors.mit.edu/sage/spkg/upstream/surf/surf-1.0.6-gcc6.tar.gz + ... + [surf-1.0.6-gcc6] Setting up build directory for surf-1.0.6-gcc6 + ... + [surf-1.0.6-gcc6] /usr/bin/ld: cannot find -lfl + [surf-1.0.6-gcc6] collect2: error: ld returned 1 exit status + [surf-1.0.6-gcc6] Makefile:504: recipe for target 'surf' failed + [surf-1.0.6-gcc6] make[3]: *** [surf] Error 1 + ... + [surf-1.0.6-gcc6] Error installing package surf-1.0.6-gcc6 + ... + Makefile:2088: recipe for target '/sage/local/var/lib/sage/installed/surf-1.0.6-gcc6' failed + make[1]: *** [/sage/local/var/lib/sage/installed/surf-1.0.6-gcc6] Error 1 + make[1]: Target 'surf' not remade because of errors. + make[1]: Leaving directory '/sage/build/make' + ... + Error building Sage. + + The following package(s) may have failed to build (not necessarily + during this run of 'make surf'): + + * package: surf-1.0.6-gcc6 + last build time: Mar 26 22:07 + log file: /sage/logs/pkgs/surf-1.0.6-gcc6.log + build directory: /sage/local/var/tmp/sage/build/surf-1.0.6-gcc6 + + ... + Makefile:31: recipe for target 'surf' failed + make: *** [surf] Error 1 + The command '/bin/sh -c make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE}' + returned a non-zero code: 2 - The following package(s) may have failed to build (not necessarily - during this run of 'make surf'): +Note that no image id is shown at the end; the build failed, and no +image is created. However, the container in which the last step of +the build was attempted exists - * package: surf-1.0.6-gcc6 - last build time: Mar 26 22:07 - log file: /sage/logs/pkgs/surf-1.0.6-gcc6.log - build directory: /sage/local/var/tmp/sage/build/surf-1.0.6-gcc6 +.. code-block:: console - ... - Makefile:31: recipe for target 'surf' failed - make: *** [surf] Error 1 - The command '/bin/sh -c make SAGE_SPKG="sage-spkg -y -o" ${USE_MAKEFLAGS} ${TARGETS_PRE}' - returned a non-zero code: 2 + $docker ps -a |head -n3 + CONTAINER ID IMAGE COMMAND CREATED STATUS + 61833bea6a6d 7b51411520c3 "/bin/sh -c 'make SA…" 9 minutes ago Exited (2) 1 minute ago + 73987568712c ubuntu-latest-minimal-17 "/bin/bash" 24 hours ago Exited (0) 23 hours ago -Note that no image id is shown at the end; the build failed, and no -image is created. However, the container in which the last step of -the build was attempted exists:: - - [mkoeppe@sage sage]$ docker ps -a |head -n3 - CONTAINER ID IMAGE COMMAND CREATED STATUS - 61833bea6a6d 7b51411520c3 "/bin/sh -c 'make SA…" 9 minutes ago Exited (2) 1 minute ago - 73987568712c ubuntu-latest-minimal-17 "/bin/bash" 24 hours ago Exited (0) 23 hours ago - -We can copy the build directory from the container for inspection:: - - [mkoeppe@sage sage]$ docker cp 61833bea6a6d:/sage/local/var/tmp/sage/build ubuntu-build - [mkoeppe@sage sage]$ ls ubuntu-build/surf*/src - AUTHORS TODO curve misc - COPYING acinclude.m4 debug missing - ChangeLog aclocal.m4 dither mkinstalldirs - INSTALL background.pic docs mt - Makefile config.guess draw src - Makefile.am config.log drawfunc surf.1 - Makefile.global config.status examples surf.xpm - Makefile.in config.sub gtkgui yaccsrc - NEWS configure image-formats - README configure.in install-sh +We can copy the build directory from the container for inspection -Alternatively, we can use ``docker commit`` as explained earlier to -create an image from the container:: +.. code-block:: console - [mkoeppe@sage sage]$ docker commit 61833bea6a6d - sha256:003fbd511016fe305bd8494bb1747f0fbf4cb2c788b4e755e9099d9f2014a60d - [mkoeppe@sage sage]$ docker run -it 003fbd511 bash - root@2d9ac65f4572:/sage# (cd /sage/local/var/tmp/sage/build/surf* && /sage/sage --buildsh) + $ docker cp 61833bea6a6d:/sage/local/var/tmp/sage/build ubuntu-build + $ ls ubuntu-build/surf*/src + AUTHORS TODO curve misc + COPYING acinclude.m4 debug missing + ChangeLog aclocal.m4 dither mkinstalldirs + INSTALL background.pic docs mt + Makefile config.guess draw src + Makefile.am config.log drawfunc surf.1 + Makefile.global config.status examples surf.xpm + Makefile.in config.sub gtkgui yaccsrc + NEWS configure image-formats + README configure.in install-sh - Starting subshell with Sage environment variables set. Don't forget - to exit when you are done. - ... - Note: SAGE_ROOT=/sage - (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ ls /usr/lib/libfl* - /usr/lib/libflint-2.5.2.so /usr/lib/libflint-2.5.2.so.13.5.2 /usr/lib/libflint.a /usr/lib/libflint.so - (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-get update && apt-get install apt-file - (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-file update - (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-file search "/usr/lib/libfl.a" - flex-old: /usr/lib/libfl.a - freebsd-buildutils: /usr/lib/libfl.a - (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-get install flex-old - (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ ./spkg-install - checking for a BSD-compatible install... /usr/bin/install -c - checking whether build environment is sane... yes - ... - /usr/bin/install -c surf /sage/local/bin/surf - /usr/bin/install -c -m 644 ./surf.1 /sage/local/share/man/man1/surf.1 - ... - make[1]: Leaving directory '/sage/local/var/tmp/sage/build/surf-1.0.6-gcc6/src' - (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ exit - root@2d9ac65f4572:/sage# exit - [mkoeppe@sage sage]$ +Alternatively, we can use ``docker commit`` as explained earlier to +create an image from the container + +.. code-block:: console + + $ docker commit 61833bea6a6d + sha256:003fbd511016fe305bd8494bb1747f0fbf4cb2c788b4e755e9099d9f2014a60d + $ docker run -it 003fbd511 bash + root@2d9ac65f4572:/sage# (cd /sage/local/var/tmp/sage/build/surf* && /sage/sage --buildsh) + + Starting subshell with Sage environment variables set. Don't forget + to exit when you are done. + ... + Note: SAGE_ROOT=/sage + (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ ls /usr/lib/libfl* + /usr/lib/libflint-2.5.2.so /usr/lib/libflint-2.5.2.so.13.5.2 /usr/lib/libflint.a /usr/lib/libflint.so + (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-get update && apt-get install apt-file + (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-file update + (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-file search "/usr/lib/libfl.a" + flex-old: /usr/lib/libfl.a + freebsd-buildutils: /usr/lib/libfl.a + (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ apt-get install flex-old + (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ ./spkg-install + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + ... + /usr/bin/install -c surf /sage/local/bin/surf + /usr/bin/install -c -m 644 ./surf.1 /sage/local/share/man/man1/surf.1 + ... + make[1]: Leaving directory '/sage/local/var/tmp/sage/build/surf-1.0.6-gcc6/src' + (sage-buildsh) root@2d9ac65f4572:surf-1.0.6-gcc6$ exit + root@2d9ac65f4572:/sage# exit + $ A standard case of bitrot. @@ -610,9 +648,11 @@ Automatic Docker-based build testing using tox is widely used for automating tests of Python projects. If you are using Docker locally, install ``tox`` for use with your system Python, -for example using:: +for example using - [mkoeppe@sage sage]$ pip install --user tox +.. code-block:: console + + $ pip install --user tox If you run Docker-in-Docker on GitHub Codespaces using our dev container configuration `.devcontainer/tox-docker-in-docker @@ -654,14 +694,18 @@ installed on the system before building Sage: - ``standard`` additionally installs all known system packages that are equivalent to standard packages of the Sage distribution, for which the mechanism ``spkg-configure.m4`` is implemented. - This corresponds to the packages listed by:: + This corresponds to the packages listed by + +.. code-block:: console - [mkoeppe@sage sage]$ sage --package list --has-file=spkg-configure.m4 :standard: + $ sage --package list --has-file=spkg-configure.m4 :standard: - ``maximal`` does the same for all standard and optional packages. - This corresponds to the packages listed by:: + This corresponds to the packages listed by + +.. code-block:: console - [mkoeppe@sage sage]$ sage --package list :standard: :optional: + $ sage --package list :standard: :optional: The factors are connected by a hyphen to name a system configuration, such as ``debian-buster-standard`` and ``centos-7-i386-minimal``. @@ -674,26 +718,32 @@ order of the factors does not matter; however, for consistency and because the ordered name is used for caching purposes, we recommend to use the factors in the listed order.) -To run an environment:: +To run an environment - [mkoeppe@sage sage]$ tox -e docker-slackware-14.2-minimal - [mkoeppe@sage sage]$ tox -e docker-ubuntu-bionic-standard +.. code-block:: console + + $ tox -e docker-slackware-14.2-minimal + $ tox -e docker-ubuntu-bionic-standard Arbitrary extra arguments to ``docker build`` can be supplied through the environment variable ``EXTRA_DOCKER_BUILD_ARGS``. For example, -for a non-silent build (``make V=1``), use:: +for a non-silent build (``make V=1``), use + +.. code-block:: console - [mkoeppe@sage sage]$ EXTRA_DOCKER_BUILD_ARGS="--build-arg USE_MAKEFLAGS=\"V=1\"" \ - tox -e docker-ubuntu-bionic-standard + $ EXTRA_DOCKER_BUILD_ARGS="--build-arg USE_MAKEFLAGS=\"V=1\"" \ + tox -e docker-ubuntu-bionic-standard By default, tox uses ``TARGETS_PRE=all-sage-local`` and ``TARGETS=build``, leading to a complete build of Sage without the documentation. If you pass positional arguments to tox (separated from tox options by ``--``), then both ``TARGETS_PRE`` and ``TARGETS`` are set to these arguments. In this way, you can build some specific -packages instead of all of Sage, for example:: +packages instead of all of Sage, for example - [mkoeppe@sage sage]$ tox -e docker-centos-8-standard -- ratpoints +.. code-block:: console + + $ tox -e docker-centos-8-standard -- ratpoints If the build succeeds, this will create a new image named ``sage-centos-8-standard-with-targets:9.1.beta9-431-gca4b5b2f33-dirty``, @@ -709,34 +759,38 @@ where You can ask for tox to create named intermediate images as well. For example, to create the images corresponding to the state of the OS after installing all system packages (``with-system-packages``) and -the one just after running the ``configure`` script (``configured``):: - - [mkoeppe@sage sage]$ DOCKER_TARGETS="with-system-packages configured with-targets" \ - tox -e docker-centos-8-standard -- ratpoints - ... - Sending build context to Docker daemon ... - Step 1/109 : ARG BASE_IMAGE=fedora:latest - Step 2/109 : FROM ${BASE_IMAGE} as with-system-packages - ... - Step 109/109 : RUN yum install -y zlib-devel || echo "(ignoring error)" - ... - Successfully built 4bb14c3d5646 - Successfully tagged sage-centos-8-standard-with-system-packages:9.1.beta9-435-g861ba33bbc-dirty - Sending build context to Docker daemon ... - ... - Successfully tagged sage-centos-8-standard-configured:9.1.beta9-435-g861ba33bbc-dirty - ... - Sending build context to Docker daemon ... - ... - Successfully tagged sage-centos-8-standard-with-targets:9.1.beta9-435-g861ba33bbc-dirty - -Let's verify that the images are available:: - - [mkoeppe@sage sage]$ docker images | head - REPOSITORY TAG IMAGE ID - sage-centos-8-standard-with-targets 9.1.beta9-435-g861ba33bbc-dirty 7ecfa86fceab - sage-centos-8-standard-configured 9.1.beta9-435-g861ba33bbc-dirty 4314929e2b4c - sage-centos-8-standard-with-system-packages 9.1.beta9-435-g861ba33bbc-dirty 4bb14c3d5646 +the one just after running the ``configure`` script (``configured``) + +.. code-block:: console + + $ DOCKER_TARGETS="with-system-packages configured with-targets" \ + tox -e docker-centos-8-standard -- ratpoints + ... + Sending build context to Docker daemon ... + Step 1/109 : ARG BASE_IMAGE=fedora:latest + Step 2/109 : FROM ${BASE_IMAGE} as with-system-packages + ... + Step 109/109 : RUN yum install -y zlib-devel || echo "(ignoring error)" + ... + Successfully built 4bb14c3d5646 + Successfully tagged sage-centos-8-standard-with-system-packages:9.1.beta9-435-g861ba33bbc-dirty + Sending build context to Docker daemon ... + ... + Successfully tagged sage-centos-8-standard-configured:9.1.beta9-435-g861ba33bbc-dirty + ... + Sending build context to Docker daemon ... + ... + Successfully tagged sage-centos-8-standard-with-targets:9.1.beta9-435-g861ba33bbc-dirty + +Let's verify that the images are available + +.. code-block:: console + + $ docker images | head + REPOSITORY TAG IMAGE ID + sage-centos-8-standard-with-targets 9.1.beta9-435-g861ba33bbc-dirty 7ecfa86fceab + sage-centos-8-standard-configured 9.1.beta9-435-g861ba33bbc-dirty 4314929e2b4c + sage-centos-8-standard-with-system-packages 9.1.beta9-435-g861ba33bbc-dirty 4bb14c3d5646 ... @@ -756,63 +810,69 @@ other prerequisites installed in your system. See ``build/pkgs/_bootstrap/distros/*.txt`` for a list of system packages that provide these prerequisites. -We start by creating a fresh (distclean) git worktree:: +We start by creating a fresh (distclean) git worktree - [mkoeppe@sage sage] git worktree add worktree-local - [mkoeppe@sage sage] cd worktree-local - [mkoeppe@sage worktree-local] ls - COPYING.txt ... Makefile ... configure.ac ... src tox.ini +.. code-block:: console -Again we build only a small package. Build targets can be passed as -positional arguments (separated from tox options by ``--``):: + $ git worktree add worktree-local + $ cd worktree-local + $ ls + COPYING.txt ... Makefile ... configure.ac ... src tox.ini - [mkoeppe@sage worktree-local] tox -e local-direct -- ratpoints - local-direct create: /Users/mkoeppe/.../worktree-local/.tox/local-direct - local-direct run-test-pre: PYTHONHASHSEED='2211987514' - ... - src/doc/bootstrap:48: installing src/doc/en/installation/debian.txt... - bootstrap:69: installing 'config/config.rpath' - configure.ac:328: installing 'config/compile' - configure.ac:113: installing 'config/config.guess' - ... - checking for a BSD-compatible install... /usr/bin/install -c - checking whether build environment is sane... yes - ... - sage-logger -p 'sage-spkg -y -o ratpoints-2.1.3.p5' '.../worktree-local/logs/pkgs/ratpoints-2.1.3.p5.log' - [ratpoints-2.1.3.p5] installing. Log file: .../worktree-local/logs/pkgs/ratpoints-2.1.3.p5.log - [ratpoints-2.1.3.p5] successfully installed. - ... - local-direct: commands succeeded - congratulations :) - -Let's investigate what happened here:: - - [mkoeppe@sage worktree-local]$ ls -la - total 2576 - drwxr-xr-x 35 mkoeppe staff 1120 Mar 26 22:20 . - drwxr-xr-x 63 mkoeppe staff 2016 Mar 27 09:35 .. - ... - lrwxr-xr-x 1 mkoeppe staff 10 Mar 26 20:34 .dockerignore -> .gitignore - -rw-r--r-- 1 mkoeppe staff 74 Mar 26 20:34 .git - ... - -rw-r--r-- 1 mkoeppe staff 1212 Mar 26 20:41 .gitignore - ... - drwxr-xr-x 7 mkoeppe staff 224 Mar 26 22:11 .tox - ... - -rw-r--r-- 1 mkoeppe staff 7542 Mar 26 20:41 Makefile - ... - lrwxr-xr-x 1 mkoeppe staff 114 Mar 26 20:45 config.log -> .tox/local-direct/log/config.log - -rwxr-xr-x 1 mkoeppe staff 90411 Mar 26 20:46 config.status - -rwxr-xr-x 1 mkoeppe staff 887180 Mar 26 20:45 configure - -rw-r--r-- 1 mkoeppe staff 17070 Mar 26 20:41 configure.ac - ... - lrwxr-xr-x 1 mkoeppe staff 103 Mar 26 20:45 logs -> .tox/local-direct/log - drwxr-xr-x 24 mkoeppe staff 768 Mar 26 20:45 m4 - lrwxr-xr-x 1 mkoeppe staff 105 Mar 26 20:45 prefix -> .tox/local-direct/local - -rwxr-xr-x 1 mkoeppe staff 4868 Mar 26 20:34 sage - drwxr-xr-x 16 mkoeppe staff 512 Mar 26 20:46 src - -rw-r--r-- 1 mkoeppe staff 13478 Mar 26 20:41 tox.ini - drwxr-xr-x 4 mkoeppe staff 128 Mar 26 20:46 upstream +Again we build only a small package. Build targets can be passed as +positional arguments (separated from tox options by ``--``): + +.. code-block:: console + + $ tox -e local-direct -- ratpoints + local-direct create: /Users/mkoeppe/.../worktree-local/.tox/local-direct + local-direct run-test-pre: PYTHONHASHSEED='2211987514' + ... + src/doc/bootstrap:48: installing src/doc/en/installation/debian.txt... + bootstrap:69: installing 'config/config.rpath' + configure.ac:328: installing 'config/compile' + configure.ac:113: installing 'config/config.guess' + ... + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + ... + sage-logger -p 'sage-spkg -y -o ratpoints-2.1.3.p5' '.../worktree-local/logs/pkgs/ratpoints-2.1.3.p5.log' + [ratpoints-2.1.3.p5] installing. Log file: .../worktree-local/logs/pkgs/ratpoints-2.1.3.p5.log + [ratpoints-2.1.3.p5] successfully installed. + ... + local-direct: commands succeeded + congratulations :) + +Let's investigate what happened here + +.. code-block:: console + + $ ls -la + total 2576 + drwxr-xr-x 35 mkoeppe staff 1120 Mar 26 22:20 . + drwxr-xr-x 63 mkoeppe staff 2016 Mar 27 09:35 .. + ... + lrwxr-xr-x 1 mkoeppe staff 10 Mar 26 20:34 .dockerignore -> .gitignore + -rw-r--r-- 1 mkoeppe staff 74 Mar 26 20:34 .git + ... + -rw-r--r-- 1 mkoeppe staff 1212 Mar 26 20:41 .gitignore + ... + drwxr-xr-x 7 mkoeppe staff 224 Mar 26 22:11 .tox + ... + -rw-r--r-- 1 mkoeppe staff 7542 Mar 26 20:41 Makefile + ... + lrwxr-xr-x 1 mkoeppe staff 114 Mar 26 20:45 config.log -> .tox/local-direct/log/config.log + -rwxr-xr-x 1 mkoeppe staff 90411 Mar 26 20:46 config.status + -rwxr-xr-x 1 mkoeppe staff 887180 Mar 26 20:45 configure + -rw-r--r-- 1 mkoeppe staff 17070 Mar 26 20:41 configure.ac + ... + lrwxr-xr-x 1 mkoeppe staff 103 Mar 26 20:45 logs -> .tox/local-direct/log + drwxr-xr-x 24 mkoeppe staff 768 Mar 26 20:45 m4 + lrwxr-xr-x 1 mkoeppe staff 105 Mar 26 20:45 prefix -> .tox/local-direct/local + -rwxr-xr-x 1 mkoeppe staff 4868 Mar 26 20:34 sage + drwxr-xr-x 16 mkoeppe staff 512 Mar 26 20:46 src + -rw-r--r-- 1 mkoeppe staff 13478 Mar 26 20:41 tox.ini + drwxr-xr-x 4 mkoeppe staff 128 Mar 26 20:46 upstream There is no ``local`` subdirectory. This is part of a strategy to keep the source tree clean to the extent possible. In particular: @@ -820,9 +880,11 @@ keep the source tree clean to the extent possible. In particular: - ``tox`` configured the build to use a separate ``$SAGE_LOCAL`` hierarchy in a directory under the tox environment directory ``.tox/local-direct``. It created a symbolic link ``prefix`` that - points there, for convenience:: + points there, for convenience + +.. code-block:: console - [mkoeppe@sage worktree-local]$ ls -l prefix/lib/*rat* + $ ls -l prefix/lib/*rat* -rw-r--r-- 1 mkoeppe staff 165968 Mar 26 20:46 prefix/lib/libratpoints.a - Likewise, it created a separate ``logs`` directory, again under the @@ -867,51 +929,53 @@ the Sage distribution. A good way to install them is using the Homebrew package manager. In fact, Sage provides a tox environment that automatically installs -an isolated copy of Homebrew with all prerequisites for bootstrapping:: - - [mkoeppe@sage worktree-local]$ tox -e local-homebrew-macos-minimal -- lrslib - local-homebrew-macos-minimal create: .../worktree-local/.tox/local-homebrew-macos-minimal - local-homebrew-macos-minimal run-test-pre: PYTHONHASHSEED='4246149402' - ... - Initialized empty Git repository in .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/.git/ - ... - Tapped 2 commands and 4942 formulae (5,205 files, 310.7MB). - ==> Downloading https://ftp.gnu.org/gnu/gettext/gettext-0.20.1.tar.xz - ... - ==> Pouring autoconf-2.69.catalina.bottle.4.tar.gz - ... - ==> Pouring pkg-config-0.29.2.catalina.bottle.1.tar.gz - .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/Cellar/pkg-config/0.29.2: 11 files, 623.4KB - ==> Caveats - ==> gettext - gettext is keg-only, which means it was not symlinked into .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew, - because macOS provides the BSD gettext library & some software gets confused if both are in the library path. - - If you need to have gettext first in your PATH run: - echo 'export PATH=".../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/bin:$PATH"' >> ~/.bash_profile - - For compilers to find gettext you may need to set: - export LDFLAGS="-L.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/lib" - export CPPFLAGS="-I.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/include" - ... - local-homebrew-macos-minimal run-test: commands[0] | bash -c 'export PATH=.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin && . .homebrew-build-env && ./bootstrap && ./configure --prefix=.../worktree-local/.tox/local-homebrew-macos-minimal/local && make -k V=0 ... lrslib' - ... - bootstrap:69: installing 'config/config.rpath' - ... - checking for a BSD-compatible install... /usr/bin/install -c - checking whether build environment is sane... yes - ... - configure: notice: the following SPKGs did not find equivalent system packages: cbc cliquer ... tachyon xz zeromq - checking for the package system in use... homebrew - configure: hint: installing the following system packages is recommended and may avoid building some of the above SPKGs from source: - configure: $ brew install cmake gcc gsl mpfi ninja openblas gpatch r readline xz zeromq - ... - sage-logger -p 'sage-spkg -y -o lrslib-062+autotools-2017-03-03.p1' '.../worktree-local/logs/pkgs/lrslib-062+autotools-2017-03-03.p1.log' - [lrslib-062+autotools-2017-03-03.p1] installing. Log file: .../worktree-local/logs/pkgs/lrslib-062+autotools-2017-03-03.p1.log - [lrslib-062+autotools-2017-03-03.p1] successfully installed. - ... - local-homebrew-macos-minimal: commands succeeded - congratulations :) +an isolated copy of Homebrew with all prerequisites for bootstrapping + +.. code-block:: console + + $ tox -e local-homebrew-macos-minimal -- lrslib + local-homebrew-macos-minimal create: .../worktree-local/.tox/local-homebrew-macos-minimal + local-homebrew-macos-minimal run-test-pre: PYTHONHASHSEED='4246149402' + ... + Initialized empty Git repository in .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/.git/ + ... + Tapped 2 commands and 4942 formulae (5,205 files, 310.7MB). + ==> Downloading https://ftp.gnu.org/gnu/gettext/gettext-0.20.1.tar.xz + ... + ==> Pouring autoconf-2.69.catalina.bottle.4.tar.gz + ... + ==> Pouring pkg-config-0.29.2.catalina.bottle.1.tar.gz + .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/Cellar/pkg-config/0.29.2: 11 files, 623.4KB + ==> Caveats + ==> gettext + gettext is keg-only, which means it was not symlinked into .../worktree-local/.tox/local-homebrew-macos-minimal/homebrew, + because macOS provides the BSD gettext library & some software gets confused if both are in the library path. + + If you need to have gettext first in your PATH run: + echo 'export PATH=".../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/bin:$PATH"' >> ~/.bash_profile + + For compilers to find gettext you may need to set: + export LDFLAGS="-L.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/lib" + export CPPFLAGS="-I.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/opt/gettext/include" + ... + local-homebrew-macos-minimal run-test: commands[0] | bash -c 'export PATH=.../worktree-local/.tox/local-homebrew-macos-minimal/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin && . .homebrew-build-env && ./bootstrap && ./configure --prefix=.../worktree-local/.tox/local-homebrew-macos-minimal/local && make -k V=0 ... lrslib' + ... + bootstrap:69: installing 'config/config.rpath' + ... + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + ... + configure: notice: the following SPKGs did not find equivalent system packages: cbc cliquer ... tachyon xz zeromq + checking for the package system in use... homebrew + configure: hint: installing the following system packages is recommended and may avoid building some of the above SPKGs from source: + configure: $ brew install cmake gcc gsl mpfi ninja openblas gpatch r readline xz zeromq + ... + sage-logger -p 'sage-spkg -y -o lrslib-062+autotools-2017-03-03.p1' '.../worktree-local/logs/pkgs/lrslib-062+autotools-2017-03-03.p1.log' + [lrslib-062+autotools-2017-03-03.p1] installing. Log file: .../worktree-local/logs/pkgs/lrslib-062+autotools-2017-03-03.p1.log + [lrslib-062+autotools-2017-03-03.p1] successfully installed. + ... + local-homebrew-macos-minimal: commands succeeded + congratulations :) The tox environment uses the subdirectory ``homebrew`` of the environment directory ``.tox/local-homebrew-macos-minimal`` as the @@ -985,9 +1049,11 @@ by setting environment variables. The ``local`` technology also defines a special target ``bash``: Instead of building anything with ``make``, it just starts an interactive shell. For example, in combination with the above -options:: +options + +.. code-block:: console - [mkoeppe@sage worktree-local]$ SKIP_SYSTEM_PKG_INSTALL=yes SKIP_BOOTSTRAP=1 SKIP_CONFIGURE=1 tox -e local-homebrew-macos-minimal -- bash + $$ SKIP_SYSTEM_PKG_INSTALL=yes SKIP_BOOTSTRAP=1 SKIP_CONFIGURE=1 tox -e local-homebrew-macos-minimal -- bash Automatic testing on multiple platforms on GitHub Actions @@ -1028,11 +1094,13 @@ forks of the Sage repository. To prepare this, `enable GitHub Actions `_. Thus, -for example, the following command will work:: - - $ docker run -it ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev bash - Unable to find image 'ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev' locally - dev: Pulling from sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional - d5fd17ec1767: Already exists - 67586203f0c7: Pull complete - b63c529f4777: Pull complete - ... - 159775d1a3d2: Pull complete - Digest: sha256:e6ba5e12f59c6c4668692ef4cfe4ae5f242556482664fb347bf260f32bf8e698 - Status: Downloaded newer image for ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev - root@8055a7ba0607:/sage# ./sage - ┌────────────────────────────────────────────────────────────────────┐ - │ SageMath version 9.6, Release Date: 2022-05-15 │ - │ Using Python 3.8.10. Type "help()" for help. │ - └────────────────────────────────────────────────────────────────────┘ - sage: +for example, the following command will work + +.. code-block:: console + + $ docker run -it ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev bash + Unable to find image 'ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev' locally + dev: Pulling from sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional + d5fd17ec1767: Already exists + 67586203f0c7: Pull complete + b63c529f4777: Pull complete + ... + 159775d1a3d2: Pull complete + Digest: sha256:e6ba5e12f59c6c4668692ef4cfe4ae5f242556482664fb347bf260f32bf8e698 + Status: Downloaded newer image for ghcr.io/sagemath/sage/sage-ubuntu-focal-standard-with-targets-optional:dev + root@8055a7ba0607:/sage# ./sage + ┌────────────────────────────────────────────────────────────────────┐ + │ SageMath version 9.6, Release Date: 2022-05-15 │ + │ Using Python 3.8.10. Type "help()" for help. │ + └────────────────────────────────────────────────────────────────────┘ + sage: Images whose names end with the suffix ``-with-targets-optional`` are the results of full builds and a run of ``make ptest``. They also diff --git a/src/doc/en/developer/sage_manuals.rst b/src/doc/en/developer/sage_manuals.rst index 6c3320d332e..8f940ffcc4c 100644 --- a/src/doc/en/developer/sage_manuals.rst +++ b/src/doc/en/developer/sage_manuals.rst @@ -47,9 +47,11 @@ Editing the documentation After modifying some files in the Sage tutorial (:sage_root:`src/doc/en/tutorial/`), you will want to visualize the result. In -order to build a **html** version of this document, type:: +order to build a **html** version of this document, type - sage --docbuild tutorial html +.. code-block:: console + + $ sage --docbuild tutorial html You can now open :file:`SAGE_ROOT/local/share/doc/sage/html/en/tutorial/index.html` in your web browser. @@ -62,15 +64,19 @@ your web browser. **Run doctests:** All files must pass tests. After modifying a document (e.g. ``tutorial``), you can run tests with the following command (see -:ref:`chapter-testing`):: +:ref:`chapter-testing`) + +.. code-block:: console - sage -tp SAGE_ROOT/src/doc/en/tutorial/ + $ sage -tp SAGE_ROOT/src/doc/en/tutorial/ **Reference manual:** as this manual is mostly generated from Sage's source code, you will need to build Sage in order to see the changes you made to some -function's documentation. Type:: +function's documentation. Type + +.. code-block:: console - sage -b && sage --docbuild reference html + $ sage -b && sage --docbuild reference html .. _chapter-sage_manuals_links: @@ -315,19 +321,25 @@ script. The content of the ``sage --docbuild`` script is defined in the ``sphinx-build`` script which does all of the real work. It is designed to be a replacement for the default Makefiles generated by the ``sphinx-quickstart`` script. The general form of the command -is:: +is + +.. code-block:: console + + $ sage --docbuild - sage --docbuild +For example -For example:: +.. code-block:: console - sage --docbuild reference html + $ sage --docbuild reference html Two **help** commands which give plenty of documentation for the ``sage ---docbuild`` script:: +--docbuild`` script - sage --docbuild -h # short help message - sage --docbuild -H # a more comprehensive one +.. code-block:: console + + $ sage --docbuild -h # short help message + $ sage --docbuild -H # a more comprehensive one **Output formats:** All output formats supported by Sphinx (e.g. pdf) can be used in Sage. See ``_. @@ -335,9 +347,11 @@ used in Sage. See ``_. **Broken links:** in order to build the documentation while reporting the broken links that it contains, use the ``--warn-links`` flag. Note that Sphinx will not rebuild a document that has not been updated, and thus not report its broken -links:: +links + +.. code-block:: console - sage --docbuild --warn-links reference html + $ sage --docbuild --warn-links reference html .. _section-manuals-names: @@ -353,14 +367,18 @@ The ```` has the form: where ``lang`` is a two-letter language code, and ``name`` is the descriptive name of the document. If the language is not specified, then it defaults to English (``en``). The following two commands do -the exact same thing:: +the exact same thing + +.. code-block:: console + + $ sage --docbuild tutorial html + $ sage --docbuild en/tutorial html - sage --docbuild tutorial html - sage --docbuild en/tutorial html +To specify the French version of the tutorial, you would simply run -To specify the French version of the tutorial, you would simply run:: +.. code-block:: console - sage --docbuild fr/tutorial html + $ sage --docbuild fr/tutorial html Syntax highlighting Cython code diff --git a/src/doc/en/developer/tools.rst b/src/doc/en/developer/tools.rst index ca2fa61acf0..59b163e8b74 100644 --- a/src/doc/en/developer/tools.rst +++ b/src/doc/en/developer/tools.rst @@ -11,13 +11,13 @@ Development and Testing Tools uv == -`uv `_ is a versatile tool for -managing and synchronizing project dependencies. +`uv `_ is a versatile tool for +managing and synchronizing project dependencies. -The lockfile `uv.lock` in the root captures the exact package versions for +The lockfile `uv.lock` in the root captures the exact package versions for all systems and ensures consistent, reproducible installations. -It is automatically updated during ``uv`` operations like ``uv add`` -and ``uv run``, or explicitly with ``uv lock``. +It is automatically updated during ``uv`` operations like ``uv add`` +and ``uv run``, or explicitly with ``uv lock``. Moreover, it is periodically updated by `Renovate `_. You can also manually update it by running ``uv lock -U``. @@ -52,36 +52,38 @@ you can just type ``tox`` instead.) This configuration provides an entry point for various testing/linting methods, known as "tox environments". We can type ``./sage --advanced`` to see what is -available:: - - $ ./sage --advanced - SageMath version 9.2 - ... - Testing files: - ... - --tox [options] -- general entry point for testing - and linting of the Sage library - -e -- run specific test environments; default: - doctest,coverage,startuptime,pycodestyle-minimal,relint,codespell,rst,ruff-minimal - doctest -- run the Sage doctester - (same as "sage -t") - coverage -- give information about doctest coverage of files - (same as "sage --coverage[all]") - startuptime -- display how long each component of Sage takes to start up - (same as "sage --startuptime") - pycodestyle-minimal -- check against Sage's minimal style conventions - relint -- check whether some forbidden patterns appear - codespell -- check for misspelled words in source code - rst -- validate Python docstrings markup as reStructuredText - ruff-minimal -- check against Sage's minimal style conventions - coverage.py -- run the Sage doctester with Coverage.py - coverage.py-html -- run the Sage doctester with Coverage.py, generate HTML report - pyright -- run the static typing checker pyright - pycodestyle -- check against the Python style conventions of PEP8 - cython-lint -- check Cython files for code style - ruff -- check against Python style conventions - -p auto -- run test environments in parallel - --help -- show tox help +available + +.. code-block:: console + + $ ./sage --advanced + SageMath version 9.2 + ... + Testing files: + ... + --tox [options] -- general entry point for testing + and linting of the Sage library + -e -- run specific test environments; default: + doctest,coverage,startuptime,pycodestyle-minimal,relint,codespell,rst,ruff-minimal + doctest -- run the Sage doctester + (same as "sage -t") + coverage -- give information about doctest coverage of files + (same as "sage --coverage[all]") + startuptime -- display how long each component of Sage takes to start up + (same as "sage --startuptime") + pycodestyle-minimal -- check against Sage's minimal style conventions + relint -- check whether some forbidden patterns appear + codespell -- check for misspelled words in source code + rst -- validate Python docstrings markup as reStructuredText + ruff-minimal -- check against Sage's minimal style conventions + coverage.py -- run the Sage doctester with Coverage.py + coverage.py-html -- run the Sage doctester with Coverage.py, generate HTML report + pyright -- run the static typing checker pyright + pycodestyle -- check against the Python style conventions of PEP8 + cython-lint -- check Cython files for code style + ruff -- check against Python style conventions + -p auto -- run test environments in parallel + --help -- show tox help Doctest @@ -183,52 +185,56 @@ on the first use. Sage defines two configurations for pycodestyle. The command ``./sage -tox -e pycodestyle-minimal`` uses pycodestyle in a minimal configuration. -As of Sage 9.5, the entire Sage library conforms to this configuration:: +As of Sage 9.5, the entire Sage library conforms to this configuration - $ ./sage -tox -e pycodestyle-minimal -- src/sage/ - pycodestyle-minimal installed: pycodestyle==2.8.0 - pycodestyle-minimal run-test-pre: PYTHONHASHSEED='28778046' - pycodestyle-minimal run-test: commands[0] | pycodestyle --select E401,E70,W605,E711,E712,E721 sage - ___________ summary ____________ - pycodestyle-minimal: commands succeeded - congratulations :) +.. code-block:: console + + $ ./sage -tox -e pycodestyle-minimal -- src/sage/ + pycodestyle-minimal installed: pycodestyle==2.8.0 + pycodestyle-minimal run-test-pre: PYTHONHASHSEED='28778046' + pycodestyle-minimal run-test: commands[0] | pycodestyle --select E401,E70,W605,E711,E712,E721 sage + ___________ summary ____________ + pycodestyle-minimal: commands succeeded + congratulations :) When preparing a branch for a Sage ticket, developers should verify that ``./sage -tox -e pycodestyle-minimal`` passes. The second configuration is used with the command ``./sage -tox -e pycodestyle`` and runs a -more thorough check:: - - $ ./sage -tox -e pycodestyle -- src/sage/quadratic_forms/quadratic_form.py - pycodestyle installed: pycodestyle==2.8.0 - pycodestyle run-test-pre: PYTHONHASHSEED='2520226550' - pycodestyle run-test: commands[0] | pycodestyle sage/quadratic_forms/quadratic_form.py - sage/quadratic_forms/quadratic_form.py:135:9: E225 missing whitespace around operator - sage/quadratic_forms/quadratic_form.py:163:64: E225 missing whitespace around operator - sage/quadratic_forms/quadratic_form.py:165:52: E225 missing whitespace around operator - sage/quadratic_forms/quadratic_form.py:173:42: E228 missing whitespace around modulo operator - ... - sage/quadratic_forms/quadratic_form.py:1620:9: E266 too many leading '#' for block comment - sage/quadratic_forms/quadratic_form.py:1621:9: E266 too many leading '#' for block comment - 25 E111 indentation is not a multiple of 4 - 2 E117 over-indented - 129 E127 continuation line over-indented for visual indent - 1 E128 continuation line under-indented for visual indent - 4 E201 whitespace after '[' - 4 E202 whitespace before ']' - 2 E222 multiple spaces after operator - 7 E225 missing whitespace around operator - 1 E228 missing whitespace around modulo operator - 25 E231 missing whitespace after ',' - 1 E262 inline comment should start with '# ' - 3 E265 block comment should start with '# ' - 62 E266 too many leading '#' for block comment - 2 E272 multiple spaces before keyword - 2 E301 expected 1 blank line, found 0 - 17 E303 too many blank lines (2) - ERROR: InvocationError for command .../pycodestyle sage/quadratic_forms/quadratic_form.py (exited with code 1) - ___________ summary ____________ - ERROR: pycodestyle: commands failed +more thorough check + +.. code-block:: console + + $ ./sage -tox -e pycodestyle -- src/sage/quadratic_forms/quadratic_form.py + pycodestyle installed: pycodestyle==2.8.0 + pycodestyle run-test-pre: PYTHONHASHSEED='2520226550' + pycodestyle run-test: commands[0] | pycodestyle sage/quadratic_forms/quadratic_form.py + sage/quadratic_forms/quadratic_form.py:135:9: E225 missing whitespace around operator + sage/quadratic_forms/quadratic_form.py:163:64: E225 missing whitespace around operator + sage/quadratic_forms/quadratic_form.py:165:52: E225 missing whitespace around operator + sage/quadratic_forms/quadratic_form.py:173:42: E228 missing whitespace around modulo operator + ... + sage/quadratic_forms/quadratic_form.py:1620:9: E266 too many leading '#' for block comment + sage/quadratic_forms/quadratic_form.py:1621:9: E266 too many leading '#' for block comment + 25 E111 indentation is not a multiple of 4 + 2 E117 over-indented + 129 E127 continuation line over-indented for visual indent + 1 E128 continuation line under-indented for visual indent + 4 E201 whitespace after '[' + 4 E202 whitespace before ']' + 2 E222 multiple spaces after operator + 7 E225 missing whitespace around operator + 1 E228 missing whitespace around modulo operator + 25 E231 missing whitespace after ',' + 1 E262 inline comment should start with '# ' + 3 E265 block comment should start with '# ' + 62 E266 too many leading '#' for block comment + 2 E272 multiple spaces before keyword + 2 E301 expected 1 blank line, found 0 + 17 E303 too many blank lines (2) + ERROR: InvocationError for command .../pycodestyle sage/quadratic_forms/quadratic_form.py (exited with code 1) + ___________ summary ____________ + ERROR: pycodestyle: commands failed When preparing a branch for a PR that adds new code, developers should verify that ``./sage -tox -e pycodestyle`` does not @@ -242,25 +248,27 @@ makes it harder for reviewers to evaluate the changes. By passing the options ``--count -qq`` we can reduce the output to only show the number of style violation warnings. This can be helpful for planning work on coding-style clean-up PRs that focus on one -or a few related issues:: - - $ ./sage -tox -e pycodestyle -- --count -qq src/sage - pycodestyle installed: pycodestyle==2.8.0 - pycodestyle run-test-pre: PYTHONHASHSEED='3166223974' - pycodestyle run-test: commands[0] | pycodestyle --count -qq sage - 557 E111 indentation is not a multiple of 4 - 1 E112 expected an indented block - 194 E114 indentation is not a multiple of 4 (comment) - ... - 7 E743 ambiguous function definition 'l' - 335 W291 trailing whitespace - 4 W292 no newline at end of file - 229 W293 blank line contains whitespace - 459 W391 blank line at end of file - 97797 - ERROR: InvocationError for command .../pycodestyle --count -qq sage (exited with code 1) - ___________ summary ____________ - ERROR: pycodestyle: commands failed +or a few related issues + +.. code-block:: console + + $ ./sage -tox -e pycodestyle -- --count -qq src/sage + pycodestyle installed: pycodestyle==2.8.0 + pycodestyle run-test-pre: PYTHONHASHSEED='3166223974' + pycodestyle run-test: commands[0] | pycodestyle --count -qq sage + 557 E111 indentation is not a multiple of 4 + 1 E112 expected an indented block + 194 E114 indentation is not a multiple of 4 (comment) + ... + 7 E743 ambiguous function definition 'l' + 335 W291 trailing whitespace + 4 W292 no newline at end of file + 229 W293 blank line contains whitespace + 459 W391 blank line at end of file + 97797 + ERROR: InvocationError for command .../pycodestyle --count -qq sage (exited with code 1) + ___________ summary ____________ + ERROR: pycodestyle: commands failed *Installation:* (for manual use:) ``pip install -U pycodestyle --user`` @@ -341,24 +349,26 @@ Codespell `Codespell `_ uses a dictionary to check for misspelled words in source code. -Sage defines a configuration for codespell:: - - $ ./sage -tox -e codespell -- src/sage/homology/ - codespell installed: codespell==2.1.0 - codespell run-test-pre: PYTHONHASHSEED='1285169064' - codespell run-test: commands[0] | codespell '--skip=*.png,*.jpg,*.JPG,*.inv,*.dia,*.pdf,*.ico,*#*,*~*,*.bak,*.orig,*.log,*.sobj,*.tar,*.gz,*.pyc,*.o,*.sws,*.so,*.a,.DS_Store' --skip=doc/ca,doc/de,doc/es,doc/hu,doc/ja,doc/ru,doc/fr,doc/it,doc/pt,doc/tr --skip=src/doc/ca,src/doc/de,src/doc/es,src/doc/hu,src/doc/ja,src/doc/ru,src/doc/fr,src/doc/it,src/doc/pt,src/doc/tr '--skip=.git,.tox,worktree*,dist,upstream,logs,local,cythonized,scripts-3,autom4te.cache,tmp,lib.*,*.egg-info' --dictionary=- --dictionary=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-dictionary.txt --ignore-words=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-ignore.txt sage/homology - sage/homology/hochschild_complex.py:271: mone ==> mono, money, none - sage/homology/hochschild_complex.py:277: mone ==> mono, money, none - sage/homology/hochschild_complex.py:280: mone ==> mono, money, none - sage/homology/chain_complex.py:2185: mor ==> more - sage/homology/chain_complex.py:2204: mor ==> more - sage/homology/chain_complex.py:2210: mor ==> more - sage/homology/chain_complex.py:2211: mor ==> more - sage/homology/chain_complex.py:2214: mor ==> more - sage/homology/chain_complex.py:2215: mor ==> more - ERROR: InvocationError for command .../codespell '--skip=*.png,...' --dictionary=- --dictionary=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-dictionary.txt --ignore-words=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-ignore.txt sage/homology (exited with code 65) - ___________ summary ____________ - ERROR: codespell: commands failed +Sage defines a configuration for codespell + +.. code-block:: console + + $./sage -tox -e codespell -- src/sage/homology/ + codespell installed: codespell==2.1.0 + codespell run-test-pre: PYTHONHASHSEED='1285169064' + codespell run-test: commands[0] | codespell '--skip=*.png,*.jpg,*.JPG,*.inv,*.dia,*.pdf,*.ico,*#*,*~*,*.bak,*.orig,*.log,*.sobj,*.tar,*.gz,*.pyc,*.o,*.sws,*.so,*.a,.DS_Store' --skip=doc/ca,doc/de,doc/es,doc/hu,doc/ja,doc/ru,doc/fr,doc/it,doc/pt,doc/tr --skip=src/doc/ca,src/doc/de,src/doc/es,src/doc/hu,src/doc/ja,src/doc/ru,src/doc/fr,src/doc/it,src/doc/pt,src/doc/tr '--skip=.git,.tox,worktree*,dist,upstream,logs,local,cythonized,scripts-3,autom4te.cache,tmp,lib.*,*.egg-info' --dictionary=- --dictionary=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-dictionary.txt --ignore-words=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-ignore.txt sage/homology + sage/homology/hochschild_complex.py:271: mone ==> mono, money, none + sage/homology/hochschild_complex.py:277: mone ==> mono, money, none + sage/homology/hochschild_complex.py:280: mone ==> mono, money, none + sage/homology/chain_complex.py:2185: mor ==> more + sage/homology/chain_complex.py:2204: mor ==> more + sage/homology/chain_complex.py:2210: mor ==> more + sage/homology/chain_complex.py:2211: mor ==> more + sage/homology/chain_complex.py:2214: mor ==> more + sage/homology/chain_complex.py:2215: mor ==> more + ERROR: InvocationError for command .../codespell '--skip=*.png,...' --dictionary=- --dictionary=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-dictionary.txt --ignore-words=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-ignore.txt sage/homology (exited with code 65) + ___________ summary ____________ + ERROR: codespell: commands failed *Configuration:* @@ -440,34 +450,42 @@ Act `act `_ is a tool, written in Go, and using Docker, to run GitHub Actions locally; in particular, it speeds up developing Actions. -We recommend using ``gh extension`` facility to install ``act``. :: +We recommend using ``gh extension`` facility to install ``act``. : + +.. code-block:: console - [alice@localhost sage]$ gh extension install https://github.com/nektos/gh-act + $ gh extension install https://github.com/nektos/gh-act Extra steps needed for configuration of Docker to run Actions locally can be found on `act's GitHub `_ Here we give a very short sampling of ``act``'s capabilities. If you installed standalone ``act``, it should be invoked as ``act``, not as ``gh act``. -After the set up, one can e.g. list all the available linting actions:: +After the set up, one can e.g. list all the available linting actions - [alice@localhost sage]$ gh act -l | grep lint +.. code-block:: console + + $ gh act -l | grep lint 0 lint-pycodestyle Code style check with pycodestyle Lint lint.yml push,pull_request 0 lint-relint Code style check with relint Lint lint.yml push,pull_request 0 lint-rst Validate docstring markup as RST Lint lint.yml push,pull_request - [alice@localhost sage]$ + $ + +run a particular action ``lint-rst`` -run a particular action ``lint-rst`` :: +.. code-block:: console - [alice@localhost sage]$ gh act -j lint-rst + $ gh act -j lint-rst ... and so on. By default, ``act`` pulls all the data needed from the next, but it can also cache it, -speeding up repeated runs quite a lot. The following repeats running of ``lint-rst`` using cached data:: +speeding up repeated runs quite a lot. The following repeats running of ``lint-rst`` using cached data + +.. code-block:: console - [alice@localhost sage]$ gh act -p false -r -j lint-rst + $ gh act -p false -r -j lint-rst [Lint/Validate docstring markup as RST] Start image=catthehacker/ubuntu:act-latest ... | rst: commands[0] /home/alice/work/software/sage/src> flake8 --select=RST diff --git a/src/doc/en/developer/walkthrough.rst b/src/doc/en/developer/walkthrough.rst index ac889119994..7f59e4c3180 100644 --- a/src/doc/en/developer/walkthrough.rst +++ b/src/doc/en/developer/walkthrough.rst @@ -19,34 +19,46 @@ If you are in a hurry, you can skip the details and just follow these steps: 1. Install Git (see :ref:`section-git-install`) and `Conda `_. -2. Clone the Sage repository from GitHub:: +2. Clone the Sage repository from GitHub - $ git clone --origin upstream https://github.com/sagemath/sage.git + .. code-block:: console -3. Change into the directory:: - - $ cd sage + $ git clone --origin upstream https://github.com/sagemath/sage.git -4. Create a new Conda environment:: - - $ conda env create --file environment-3.12-linux.yml --name sage-dev - $ conda activate sage-dev +3. Change into the directory - Replace ``environment-3.12-linux.yml`` with the appropriate file for your system. + .. code-block:: console -5. Build and install Sage:: + $ cd sage - $ pip install --no-build-isolation --editable . +4. Create a new Conda environment + + .. code-block:: console + + $ conda env create --file environment-3.12-linux.yml --name sage-dev + $ conda activate sage-dev + + Replace ``environment-3.12-linux.yml`` with the appropriate file for your system. -6. Create a new branch for your changes:: +5. Build and install Sage - $ git checkout -b my_branch develop + .. code-block:: console -7. Make your changes, and push them to your fork on GitHub:: + $ pip install --no-build-isolation --editable . - $ git add . - $ git commit -m "Your commit message here" - $ git push origin my_branch +6. Create a new branch for your changes + + .. code-block:: console + + $ git checkout -b my_branch develop + +7. Make your changes, and push them to your fork on GitHub + + .. code-block:: console + + $ git add . + $ git commit -m "Your commit message here" + $ git push origin my_branch 8. Create a pull request on GitHub to merge your changes into the Sage repository. @@ -55,7 +67,9 @@ If you are in a hurry, you can skip the details and just follow these steps: Checking Git ============ -First, open a shell (for instance, Terminal on Mac) and check that Git works:: +First, open a shell (for instance, Terminal on Mac) and check that Git works + +.. code-block:: console $ git --version git version xyz @@ -65,13 +79,15 @@ installed; now is the time to install it. See :ref:`section-git-install` for instructions. Because we also track who does what changes with Git, you must tell -Git how you want to be known. Check if Git knows you:: +Git how you want to be known. Check if Git knows you + +.. code-block:: console $ git config --global user.name Alice Adventure $ git config --global user.email alice@wonderland.com - + If you see your name and email address, then you are all set. This name/email combination ends up in commits. So if it's not set yet, do it now before you forget! This only needs to be done once. See @@ -82,8 +98,10 @@ before you forget! This only needs to be done once. See Obtaining the Sage source code ============================== -Obviously one needs the Sage source code to develop. You can download it -from our Sage repository on GitHub:: +Obviously one needs the Sage source code to develop. You can download it +from our Sage repository on GitHub + +.. code-block:: console $ git clone --origin upstream https://github.com/sagemath/sage.git Cloning into 'sage'... @@ -97,13 +115,17 @@ Building Sage Sage is a large project with many dependencies. To build it, we recommend using Conda. If you don't have Conda installed, you can install it -by following the `official instructions `_:: - +by following the `official instructions `_ + +.. code-block:: console + $ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" $ bash Miniforge3-$(uname)-$(uname -m).sh -Now create and activate a new conda environment with the dependencies of Sage -and a few additional developer tools:: +Now create and activate a new conda environment with the dependencies of Sage +and a few additional developer tools + +.. code-block:: console $ conda env create --file environment-3.12-linux.yml --name sage-dev $ conda activate sage-dev @@ -111,7 +133,9 @@ and a few additional developer tools:: Replace ``environment-3.12-linux.yml`` with the appropriate file for your system. You can find the environment files in the root directory of the Sage repository. -Now you can build and install Sage::: +Now you can build and install Sage: + +.. code-block:: console $ pip install --no-build-isolation --editable . @@ -119,7 +143,7 @@ This will install Sage in the current Conda environment. You can then start Sage from the command line with ``sage``. For more information on building Sage we refer to the section `building -from source <../installation/meson.html>`_ in the Sage installation guide. +from source <../installation/meson.html>`_ in the Sage installation guide. .. _section-walkthrough-branch: @@ -131,7 +155,9 @@ Sage repo. A branch is a copy (except that it doesn't take up twice the space) of the Sage source code where you can store your modifications to the Sage source code (and which you can push to your fork of the Sage repository on GitHub). -To begin with, type the command ``git branch``. You will see the following:: +To begin with, type the command ``git branch``. You will see the following + +.. code-block:: console $ git branch * develop @@ -141,14 +167,18 @@ The asterisk shows you which branch you are on. Without an argument, the ``git branch`` command displays a list of all local branches with the current one marked by an asterisk. -It is easy to create a new branch, as follows:: +It is easy to create a new branch, as follows + +.. code-block:: console $ git checkout -b last_twin_prime develop This will create a new branch named ``last_twin_prime`` based on -the ``develop`` branch and switch to it. +the ``develop`` branch and switch to it. + +Now if you use the command ``git branch``, you will see the following -Now if you use the command ``git branch``, you will see the following:: +.. code-block:: console $ git branch develop @@ -171,7 +201,9 @@ throughout. The Git command ``git status`` is probably the most important of all Git commands. It tells you which files changed, and how to continue with recording -the changes:: +the changes + +.. code-block:: console $ git status On branch last_twin_prime @@ -189,7 +221,9 @@ the changes:: no changes added to commit (use "git add" and/or "git commit -a") -To dig deeper into what was changed in the files you can use:: +To dig deeper into what was changed in the files you can use + +.. code-block:: console $ git diff some_file.py @@ -202,12 +236,12 @@ Testing changes =============== Once you have made any changes, you of course want to try out -your edits. All changes to Python and Cython files take effect immediately +your edits. All changes to Python and Cython files take effect immediately after restarting Sage, so there is no need to explicitly rebuild Sage. -The changes can be tested by running Sage and verifying that the modifications -work as expected. For example, if you modified a function, you can call it -directly in Sage to ensure it behaves as intended. +The changes can be tested by running Sage and verifying that the modifications +work as expected. For example, if you modified a function, you can call it +directly in Sage to ensure it behaves as intended. Additionally, you can write or modify doctests in the relevant files to confirm the correctness of your changes. @@ -215,7 +249,7 @@ To run the doctests for a specific file, use the following command:: $ ./sage -t path/to/your/file.py -This will execute all the doctests in the specified file and report any +This will execute all the doctests in the specified file and report any failures. Make sure all tests pass before proceeding (see :ref:`chapter-doctesting` for more details). Also, don't forget to build the documentation (see :ref:`chapter-sage_manuals`). @@ -231,7 +265,9 @@ changes. A commit is just a snapshot of the state of all files in the repository. You first need to *stage* the changed files, which tells Git which files you -want to be part of the next commit:: +want to be part of the next commit + +.. code-block:: console $ git status On branch last_twin_prime @@ -248,7 +284,9 @@ want to be part of the next commit:: new file: src/sage/primes/last_pair.py Once you are satisfied with the list of staged files, you create a new -snapshot with the ``git commit`` command:: +snapshot with the ``git commit`` command + +.. code-block:: console $ git commit ... editor opens ... @@ -260,7 +298,7 @@ This will open an editor for you to write your commit message. The commit message should generally have a one-line description, followed by an empty line, followed by further explanatory text: -.. CODE-BLOCK:: text +.. code-block:: text Added the last twin prime @@ -278,11 +316,13 @@ Open pull request Once you are happy with your changes, you can propose these for review and integration into the main project. The first step is to push your branch to your fork of the `the Sage repository -`_ on GitHub. This is done with the command:: +`_ on GitHub. This is done with the command + +.. code-block:: console $ git push origin last_twin_prime -Now you can go `to GitHub and create a pull request +Now you can go `to GitHub and create a pull request `_. See :ref:`chapter-workflows` for more details on the workflow of creating a pull request and the review process. diff --git a/src/doc/en/developer/workflows.rst b/src/doc/en/developer/workflows.rst index fbe05963947..d18023c5d45 100644 --- a/src/doc/en/developer/workflows.rst +++ b/src/doc/en/developer/workflows.rst @@ -10,9 +10,11 @@ We continue our introduction to Sage development from :ref:`chapter-walkthrough` We discuss how to push your local changes to your fork of the GitHub Sage repository so that your changes can be reviewed for inclusion in Sage. -Before proceeding, check that you have ``origin`` and ``upstream`` remotes right:: +Before proceeding, check that you have ``origin`` and ``upstream`` remotes right - [alice@localhost sage]$ git remote -v +.. code-block:: console + + $ git remote -v origin https://github.com/alice/sage.git (fetch) origin https://github.com/alice/sage.git (push) upstream https://github.com/sagemath/sage.git (fetch) @@ -53,9 +55,11 @@ Creating a new PR Suppose you have written an algorithm for calculating the last twin prime, committed the code to a local branch based upon ``develop`` branch. Now you -want to add it to Sage. You would first open a PR for that:: +want to add it to Sage. You would first open a PR for that + +.. code-block:: console - [alice@localhost sage]$ gh pr create + $ gh pr create ? Where should we push the 'last-twin-prime' branch? user/sage Creating pull request for user:last-twin-prime into develop in sagemath/sage @@ -83,9 +87,11 @@ Checking out an existing PR =========================== If you want to base your work on an existing PR or want to review the code of a PR, -then you would run:: +then you would run + +.. code-block:: console - [alice@localhost sage]$ gh pr checkout 12345 + $ gh pr checkout 12345 remote: Enumerating objects: 7, done. remote: Counting objects: 100% (7/7), done. remote: Compressing objects: 100% (7/7), done. @@ -110,9 +116,11 @@ to your local branch as described in :ref:`section-walkthrough-add-edit` and :ref:`section-walkthrough-commit`. If you are ready to share the changes up to now, upload your new commits to -your fork by:: +your fork by - [alice@localhost sage]$ git push origin +.. code-block:: console + + $ git push origin Enumerating objects: 13, done. Counting objects: 100% (13/13), done. Delta compression using up to 12 threads @@ -150,16 +158,20 @@ Merging the upstream develop branch It commonly happens that ``develop`` branch at the remote ``upstream`` was updated and you need to merge the upstream changes to your local branch. Then -you do:: +you do + +.. code-block:: console - [alice@localhost sage]$ git fetch upstream develop:develop + $ git fetch upstream develop:develop This fast-forwards your local ``develop`` branch to the upstream ``develop`` branch. -Now you go back to your working branch and merge the updated ``develop`` branch:: +Now you go back to your working branch and merge the updated ``develop`` branch + +.. code-block:: console - [alice@localhost sage]$ git merge develop + $ git merge develop .... If there was no upstream change conflicting with the changes you made locally, diff --git a/src/doc/en/installation/launching.rst b/src/doc/en/installation/launching.rst index 8ebf4001d90..021ea4feb34 100644 --- a/src/doc/en/installation/launching.rst +++ b/src/doc/en/installation/launching.rst @@ -13,27 +13,27 @@ you are strongly advised to create shortcuts for Sage as indicated in the part 6 of the "Installation steps" Section in :ref:`build-from-source-step-by-step`. Assuming that you have this shortcut, running -.. CODE-BLOCK:: bash +.. code-block:: console - sage + $ sage in a console starts a Sage session. To quit the session enter ``quit`` and then press ````. To start a Jupyter Notebook instead of a Sage console, run the command -.. CODE-BLOCK:: bash +.. code-block:: console - sage -n jupyter + $ sage -n jupyter instead of just ``sage``. To quit the Jupyter Notebook press `` + `` twice in the console where you launched the command. You can pass extra parameters to this command. For example, -.. CODE-BLOCK:: bash +.. code-block:: console - sage -n jupyter --port 8899 + $ sage -n jupyter --port 8899 will run the Jupyter server on a port different from the default (8888). In particular on WSL, this is very useful because Jupyter may not be able to @@ -67,8 +67,8 @@ Sage uses the following environment variables when it runs: - See https://docs.python.org/3/using/cmdline.html#environment-variables - for more variables used by Python (not an exhaustive list). - A brief summary can also be obtained by running `python3 --help-env`. + for more variables used by Python (not an exhaustive list). + A brief summary can also be obtained by running ``python3 --help-env``. Using a Jupyter Notebook remotely --------------------------------- @@ -76,9 +76,9 @@ Using a Jupyter Notebook remotely If Sage is installed on a remote machine to which you have ``ssh`` access, you can launch a Jupyter Notebook using a command such as -.. CODE-BLOCK:: bash +.. code-block:: console - ssh -L localhost:8888:localhost:8888 -t USER@REMOTE sage -n jupyter --no-browser --port=8888 + $ ssh -L localhost:8888:localhost:8888 -t USER@REMOTE sage -n jupyter --no-browser --port=8888 where ``USER@REMOTE`` needs to be replaced by the login details to the remote machine. This uses local port forwarding to connect your local machine to the @@ -105,7 +105,7 @@ If you plan to use JupyterLab, install that first. Now create a script called ``~/sage_nb.sh`` containing the following lines, and fill in the correct paths for your desired starting directory and ``SAGE_ROOT`` -.. CODE-BLOCK:: bash +.. code-block:: bash #!/bin/bash # Switch to desired windows directory @@ -117,16 +117,16 @@ Now create a script called ``~/sage_nb.sh`` containing the following lines, and Make it executable: -.. CODE-BLOCK:: bash +.. code-block:: console - chmod ug+x ~/sage_nb.sh + $ chmod ug+x ~/sage_nb.sh Run it to test: -.. CODE-BLOCK:: bash +.. code-block:: console - cd ~ - ./sage_nb.sh + $ cd ~ + $ ./sage_nb.sh The Jupyter(Lab) server should start in the terminal window, and you windows browser should open a page showing the Jupyter or JupyterLab starting page, at the directory you specified. @@ -180,7 +180,7 @@ available: sagemath /share/jupyter/kernels/sagemath In case the Sage kernel is not listed, you can check if the file ``kernel.json`` -is present in ``/share/jupyter/kernels/sagemath``. +is present in ``/share/jupyter/kernels/sagemath``. If it is not there, you can create it using ``jupyter kernelspec install`` as described below. @@ -191,9 +191,9 @@ that can be selected in the notebook or JupyterLab interface. Assuming that SageMath can be invoked by typing ``sage``, you can use -.. CODE-BLOCK:: bash +.. code-block:: console - sage -sh -c 'ls -d $SAGE_VENV/share/jupyter/kernels/sagemath' + $ sage -sh -c 'ls -d $SAGE_VENV/share/jupyter/kernels/sagemath' to find the location of the SageMath kernel description. Alternatively, use ``jupyter kernelspec list`` from the same environment @@ -211,34 +211,34 @@ Now assuming that the Jupyter notebook can be started by typing ``jupyter notebook``, the following command will install SageMath as a new kernel named ``sagemath-dev``. -.. CODE-BLOCK:: bash +.. code-block:: console - jupyter kernelspec install --user $(sage -sh -c 'ls -d $SAGE_VENV/share/jupyter/kernels/sagemath') --name sagemath-dev + $ jupyter kernelspec install --user $(sage -sh -c 'ls -d $SAGE_VENV/share/jupyter/kernels/sagemath') --name sagemath-dev The ``jupyter kernelspec`` approach by default does lead to about 2Gb of SageMath documentation being copied into your personal jupyter configuration directory. You can avoid that by instead putting a symlink in the relevant spot and -.. CODE-BLOCK:: bash +.. code-block:: console - jupyter --paths + $ jupyter --paths to find valid data directories for your Jupyter installation. A command along the lines of -.. CODE-BLOCK:: bash +.. code-block:: console - ln -s $(sage -sh -c 'ls -d $SAGE_VENV/share/jupyter/kernels/sagemath') $HOME/.local/share/jupyter/kernels/sagemath-dev + $ ln -s $(sage -sh -c 'ls -d $SAGE_VENV/share/jupyter/kernels/sagemath') $HOME/.local/share/jupyter/kernels/sagemath-dev can then be used to create a symlink to the SageMath kernel description in a location where your own ``jupyter`` can find it. If you have installed SageMath from source, the alternative command -.. CODE-BLOCK:: bash +.. code-block:: console - ln -s $(sage -sh -c 'ls -d $SAGE_ROOT/venv/share/jupyter/kernels/sagemath') $HOME/.local/share/jupyter/kernels/sagemath-dev + $ ln -s $(sage -sh -c 'ls -d $SAGE_ROOT/venv/share/jupyter/kernels/sagemath') $HOME/.local/share/jupyter/kernels/sagemath-dev creates a symlink that will stay current even if you switch to a different Python version later. diff --git a/src/doc/en/installation/source-distro.rst b/src/doc/en/installation/source-distro.rst index 27b73484b84..09077af1ebf 100644 --- a/src/doc/en/installation/source-distro.rst +++ b/src/doc/en/installation/source-distro.rst @@ -365,7 +365,7 @@ If .. skip -.. CODE-BLOCK:: ipycon +.. code-block:: ipycon sage: import _tkinter sage: import Tkinter @@ -378,7 +378,7 @@ does not raise an :class:`ImportError`, then it worked. Installation steps ------------------ -.. hint:: +.. hint:: The following steps use the classical ``./configure && make`` build process. The modern Meson build system is also supported, see @@ -488,14 +488,14 @@ Installation steps After Sage has started, try a simple command: - .. CODE-BLOCK:: ipycon + .. code-block:: ipycon sage: 2 + 2 4 Or something slightly more complicated: - .. CODE-BLOCK:: ipycon + .. code-block:: ipycon sage: factor(2005) 5 * 401 @@ -532,7 +532,7 @@ Installation steps script should pass along all of its arguments. For example, a ``maple`` script might look like: - .. CODE-BLOCK:: bash + .. code-block:: bash #!/bin/sh @@ -552,14 +552,14 @@ Installation steps - Copy :sage_root:`sage` to a location in your :envvar:`PATH`. If you do this, make sure you edit the line: - .. CODE-BLOCK:: bash + .. code-block:: bash #SAGE_ROOT=/path/to/sage-version at the beginning of the copied ``sage`` script according to the direction given there to something like: - .. CODE-BLOCK:: bash + .. code-block:: bash SAGE_ROOT= @@ -570,7 +570,7 @@ Installation steps ``sage`` containing the lines (note that you have to change ```` below!): - .. CODE-BLOCK:: bash + .. code-block:: bash #!/usr/bin/env bash @@ -591,7 +591,7 @@ Installation steps For example, put something similar to the following line in your :file:`.bashrc` file: - .. CODE-BLOCK:: bash + .. code-block:: bash alias sage=/sage @@ -1048,7 +1048,7 @@ Environment variables controlling the documentation build ``SAGE_JUPYTER_SERVER=http://localhost:8889``, run a local Jupyter server by - .. CODE-BLOCK:: bash + .. code-block:: bash ./sage --notebook=jupyterlab \ --ServerApp.token='secret' \ @@ -1253,14 +1253,14 @@ Start from the directory created when you used ``git clone``, perhaps looking at the hidden ``.git`` subdirectory. It will looks like this, but the exact contents can vary:: - [alice@localhost sage]$ ls .git + $ ls .git COMMIT_EDITMSG HEAD branches description gitk.cache index logs packed-refs FETCH_HEAD ORIG_HEAD config hooks info objects refs Good. Now let's see what worktrees already exist:: - [alice@localhost sage]$ git worktree list + $ git worktree list /home/alice/sage/sage c0ffeefe10 [master] We see just one line, the directory created when you used ``git clone``. @@ -1271,7 +1271,7 @@ we're on (``master``). To try out a new version of Sage, let's fetch it first from the main repository:: - [alice@localhost sage]$ git fetch upstream 10.3.beta8 + $ git fetch upstream 10.3.beta8 From https://github.com/sagemath/sage * tag 10.3.beta8 -> FETCH_HEAD @@ -1282,7 +1282,7 @@ directory containing a Sage installation cannot be moved without breaking the installation in it, it may be a good idea to choose a memorable name without much meaning:: - [alice@localhost sage]$ git worktree add worktree-purple FETCH_HEAD + $ git worktree add worktree-purple FETCH_HEAD Preparing worktree (detached HEAD 30b3d78fac) Updating files: 100% (11191/11191), done. HEAD is now at 30b3d78fac Updated SageMath version to 10.3.beta8 @@ -1290,24 +1290,24 @@ a memorable name without much meaning:: We now have a subdirectory ``worktree-purple``. This is a "linked worktree":: - [alice@localhost sage]$ git worktree list + $ git worktree list /home/alice/sage/sage c0ffeefe10 [master] /home/alice/sage/sage/worktree-purple 30b3d78fac (detached HEAD) - [alice@localhost sage]$ cd worktree-purple - [alice@localhost worktree-purple]$ cat VERSION.txt + $ cd worktree-purple + $ cat VERSION.txt SageMath version 10.3.beta8, Release Date: 2024-02-13 All worktrees created in this way share the same repository, so they have access to all branches:: - [alice@localhost worktree-purple]$ git --no-pager branch -v + $ git --no-pager branch -v * (no branch) 30b3d78fac Updated SageMath version to 10.3.beta8 + master 2a9a4267f9 Updated SageMath version to 10.2 In fact, ``.git`` here is not a directory, just a hidden file:: - [alice@localhost worktree-purple]$ ls -l .git + $ ls -l .git -rw-r--r-- 1 alice staff 59 Feb 20 18:16 .git In the new worktree, we now build Sage from scratch. This @@ -1327,11 +1327,11 @@ share it with the main worktree, let's create a symbolic link. This is an optional step that will avoid re-downloading files that you already have:: - [alice@localhost worktree-purple]$ ln -s ../upstream/ . + $ ln -s ../upstream/ . Now let's build Sage, starting with the step:: - [alice@localhost worktree-purple]$ make configure + $ make configure Refer to the file `README.md `_ for the following steps. diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index 62c64149241..98c0926172b 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -2,7 +2,7 @@ ==================== Building from source -==================== +==================== This is a short guide on how to build the Sage from source using Meson. @@ -100,7 +100,7 @@ Using Conda desired version. - To compile and install Sage in editable install, just use: - + .. code-block:: console $ pip install --no-build-isolation --editable . @@ -129,8 +129,6 @@ Depending on your distribution, install the following packages: Not yet supported. - .. .. literalinclude:: debian.txt - .. tab:: Fedora At least Fedora 41 is required. @@ -143,6 +141,11 @@ Depending on your distribution, install the following packages: .. literalinclude:: arch.txt :language: console +.. tab:: OpenSUSE + + .. literalinclude:: opensuse.txt + :language: console + .. tab:: Void Linux .. literalinclude:: void.txt @@ -152,7 +155,7 @@ Depending on your distribution, install the following packages: In the case that you want to install some dependencies manually, set the correct environment variables to point to the installed libraries: -.. code-block:: console + .. code-block:: console $ export C_INCLUDE_PATH=$C_INCLUDE_PATH:/your/path/to/include $ export CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:/your/path/to/include @@ -163,7 +166,7 @@ We also recommend to install the Python package manager To compile and install Sage in editable install, then just use: -.. code-block:: console + .. code-block:: console $ uv venv $ uv pip install \ @@ -195,27 +198,27 @@ Remarks .. note:: - Note that ``make`` is not used at all, nor is ``configure``. - This means that any Sage-the-distribution commands such as ``sage -i`` - will not work. + Note that ``make`` is not used at all, nor is ``configure``. + This means that any Sage-the-distribution commands such as ``sage -i`` + will not work. .. note:: - By default, Meson will automatically determine the number of jobs to - run in parallel based on the number of CPU available. This can be adjusted - by passing ``--config-settings=compile-args=-jN`` to ``pip install``. + By default, Meson will automatically determine the number of jobs to + run in parallel based on the number of CPU available. This can be adjusted + by passing ``--config-settings=compile-args=-jN`` to ``pip install``. - ``--verbose`` can be passed to ``pip install``, then the meson commands - internally used by pip will be printed out. + ``--verbose`` can be passed to ``pip install``, then the meson commands + internally used by pip will be printed out. .. note:: - To build the documentation, use: + To build the documentation, use: - .. code-block:: console + .. code-block:: console - $ pip install --no-build-isolation -v -v --editable ./pkgs/sage-docbuild - $ sage --docbuild all html + $ pip install --no-build-isolation -v -v --editable ./pkgs/sage-docbuild + $ sage --docbuild all html .. note:: @@ -242,9 +245,9 @@ build artifacts. Certain options are configurable at build time. The easiest way to obtain an overview of these options is by using ``meson configure``: -.. code-block:: console + .. code-block:: console - $ meson configure builddir + $ meson configure builddir This command should display the available options and their associated values. The section titled "Project options" contains the options that @@ -285,33 +288,36 @@ compilation. .. note:: - If you want to install the project to a different directory, you can specify - the ``--prefix`` option when running the ``meson setup`` command: + If you want to install the project to a different directory, you can specify + the ``--prefix`` option when running the ``meson setup`` command: - .. code-block:: console + .. code-block:: console - $ meson setup builddir --prefix=/desired/install/path -Dpython.install_env=prefix + $ meson setup builddir --prefix=/desired/install/path -Dpython.install_env=prefix - This will then install in the directory specified by ``--prefix``, - in particular the root folder will be be installed to - ``/desired/install/path/lib/python3.12/site-packages/sage``. - Usually, this directory is not on your Python path, so you have to use: + This will then install in the directory specified by ``--prefix``, + in particular the root folder will be be installed to + ``/desired/install/path/lib/python3.12/site-packages/sage``. + Usually, this directory is not on your Python path, so you have to use: - .. code-block:: console + .. code-block:: console - $ PYTHONPATH=/desired/install/path ./sage + $ PYTHONPATH=/desired/install/path ./sage -Alternatively, we can still use pip to install: + Alternatively, we can still use pip to install: -.. code-block:: console + .. code-block:: console $ pip install --no-build-isolation --config-settings=builddir=builddir --editable . +.. literalinclude:: homebrew-optional.txt + :language: console + .. tip:: - Package maintainers may want to specify further build options or need - to install to a different directory than the install prefix. - Both are supported naturally by Meson: + Package maintainers may want to specify further build options or need + to install to a different directory than the install prefix. + Both are supported naturally by Meson: .. code-block:: console @@ -319,28 +325,28 @@ Alternatively, we can still use pip to install: $ meson compile -C builddir $ DESTDIR=/path/to/staging/root meson install -C builddir - SageMath's automatic feature detection (based on the packages that - happen to be installed at build time) can be disabled in favor of - explicit configuration by passing ``-Dauto_features=disabled`` to - ``meson setup``. Afterwards, individual features must be enabled - explicitly. You can obtain a list of valid feature names through - ``meson configure``. - - By default, meson may fall back to bundled versions of certain - subprojects known as `wrap dependencies - `_. - Maintainers will typically want to disable this behavior as well - to ensure that the system dependencies are used. This can be - achieved with the `--wrap-mode flag - `_ - - With the `default `_ prefix - being ``/usr/local``, it may then install to - ``$DESTDIR/usr/local/lib/python3.12/site-packages/sage``. - - See `Meson's quick guide `_ - and `Meson's install guide `_ - for more information. + SageMath's automatic feature detection (based on the packages that + happen to be installed at build time) can be disabled in favor of + explicit configuration by passing ``-Dauto_features=disabled`` to + ``meson setup``. Afterwards, individual features must be enabled + explicitly. You can obtain a list of valid feature names through + ``meson configure``. + + By default, meson may fall back to bundled versions of certain + subprojects known as `wrap dependencies + `_. + Maintainers will typically want to disable this behavior as well + to ensure that the system dependencies are used. This can be + achieved with the `--wrap-mode flag + `_ + + With the `default `_ prefix + being ``/usr/local``, it may then install to + ``$DESTDIR/usr/local/lib/python3.12/site-packages/sage``. + + See `Meson's quick guide `_ + and `Meson's install guide `_ + for more information. Miscellaneous tips ================== diff --git a/src/doc/en/installation/troubles.rst b/src/doc/en/installation/troubles.rst index 23312faf627..5006e706adf 100644 --- a/src/doc/en/installation/troubles.rst +++ b/src/doc/en/installation/troubles.rst @@ -23,9 +23,11 @@ contained in an SPKG; these are stored in ``build/pkgs/``. As each one is built, a build log is stored in ``logs/pkgs/``, so you can browse these to find error messages. If an SPKG fails to build, the whole build process will stop soon after, so check the most recent log files -first, or run:: +first, or run - grep -li "^Error" logs/pkgs/* +.. code-block:: console + + $ grep -li "^Error" logs/pkgs/* from the top-level Sage directory to find log files with error messages in them. Send the file ``config.log`` as well as the diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 03b3548f79a..b313be44c3e 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -368,6 +368,7 @@ def set_intersphinx_mappings(app, config): # https://sphinx-copybutton.readthedocs.io/en/latest/use.html copybutton_prompt_text = r"sage: |[.][.][.][.]: |>>> |[.][.][.] |\$ " +copybutton_line_continuation_character = "\\" copybutton_prompt_is_regexp = True copybutton_exclude = '.linenos, .c1' # exclude single comments (in particular, # optional!) copybutton_only_copy_prompt_lines = True