diff --git a/README.md b/README.md index bfcafebffea..d57111b5e1b 100644 --- a/README.md +++ b/README.md @@ -132,9 +132,8 @@ in the Installation Guide. - On personal computers, any subdirectory of your :envvar:`HOME` directory should do. - - For example, you could use `SAGE_ROOT=~/sage/sage-x.y`, which we - will use as the running example below, where `x.y` is the - current Sage version. + - For example, you could use `SAGE_ROOT=~/sage/sage`, which we + will use as the running example below. - You need at least 10 GB of free disk space. @@ -152,52 +151,64 @@ in the Installation Guide. capitalization when changing into :envvar:`SAGE_ROOT` can lead to build errors for dependencies requiring exact capitalization in path names. -2. Download/unpack or clone the sources. +2. Clone the sources with `git`: - - Go to https://www.sagemath.org/download-source.html, select a mirror, - and download the file :file:`sage-x.y.tar.gz`. + - To check that `git` is available, open a terminal and enter + the following command at the shell prompt (`$`): - This compressed archive file contains the source code for Sage and - the source for all programs on which Sage depends. + $ git --version + git version 2.42.0 - - After downloading the source tarball `sage-x.y.tar.gz` into - `~/sage/`: + The exact version does not matter, but if this command gives an error, + install `git` using your package manager, using one of these commands: - $ cd ~/sage/ - $ tar xf sage-x.y.tar.gz # adapt x.y; takes a while + $ sudo pacman -S git # on Arch Linux + $ sudo apt-get update && apt-get install git # on Debian/Ubuntu + $ sudo yum install git # on Fedora/Redhat/CentOS + $ sudo zypper install git # on openSUSE + $ sudo xbps-install git # on Void Linux - This creates the subdirectory `sage-x.y`. Now change into it: + - Create the directory where `SAGE_ROOT` should be established: - $ cd sage-x.y/ # adapt x.y + $ mkdir -p ~/sage + $ cd ~/sage - - [Git] Alternatively, and required for Sage development, clone the Sage - git repository: + - Clone the Sage git repository: - $ ORIG=https://github.com/sagemath/sage.git - $ git clone -c core.symlinks=true --branch develop --tags $ORIG + $ git clone -c core.symlinks=true --filter blob:none \ + --origin upstream --branch develop --tags \ + https://github.com/sagemath/sage.git - This will create the directory `sage`. (See the section + This command obtains the most recent development release. + Replace `--branch develop` by `--branch master` to select + the most recent stable release instead. + + This will create the subdirectory `~/sage/sage`. (See the section [Setting up git](https://doc.sagemath.org/html/en/developer/git_setup.html) and the following sections in the Sage Developer's Guide for more information.) - Change into it and pick the branch you need, typically - the latest development branch: + - Change into the created subdirectory: $ cd sage - $ git checkout develop - [Windows] The Sage source tree contains symbolic links, and the build will not work if Windows line endings rather than UNIX line endings are used. - Therefore it is crucial that you unpack the source tree from the - WSL `bash` using the WSL `tar` utility and not using other - Windows tools (including mingw). Likewise, when using `git`, it - is recommended (but not necessary) to use the WSL version of - `git`. + Therefore it is recommended (but not necessary) to use the + WSL version of `git`. + +3. Install system packages. + + Either refer for this to the [section on installation from + source](https://doc.sagemath.org/html/en/installation/source.html) in the + Sage Installation Manual for compilations of system packages + that you can install. When done, skip to step 7 (bootstrapping). -3. [Linux, WSL] Install the required minimal build prerequisites. + Alternatively, follow the more fine-grained approach below. + +4. [Linux, WSL] Install the required minimal build prerequisites: - Compilers: `gcc`, `gfortran`, `g++` (GCC versions from 8.4.0 to 13.x and recent versions of Clang (LLVM) are supported). @@ -206,12 +217,12 @@ in the Installation Guide. for a discussion of suitable compilers. - Build tools: GNU `make`, GNU `m4`, `perl` (including - ``ExtUtils::MakeMaker``), `ranlib`, `git`, `tar`, `bc`. + `ExtUtils::MakeMaker`), `ranlib`, `git`, `tar`, `bc`. See [build/pkgs/_prereq/SPKG.rst](build/pkgs/_prereq/SPKG.rst) for more details. - Python 3.4 or later, or Python 2.7, a full installation including - `urllib`; but ideally version 3.9.x, 3.10.x, or 3.11.x, which + `urllib`; but ideally version 3.9.x, 3.10.x, 3.11.x, 3.12.x, which will avoid having to build Sage's own copy of Python 3. See [build/pkgs/python3/SPKG.rst](build/pkgs/python3/SPKG.rst) for more details. @@ -230,22 +241,25 @@ in the Installation Guide. [void.txt](build/pkgs/_prereq/distros/void.txt), or visit https://doc.sagemath.org/html/en/reference/spkg/_prereq.html#spkg-prereq -4. [Git] If you plan to do Sage development or otherwise work with ticket branches - and not only releases, install the bootstrapping prerequisites. See the - files in the folder +5. Optional: It is recommended that you have both LaTeX and + the ImageMagick tools (e.g. the "convert" command) installed + since some plotting functionality benefits from them. + +6. [Development] If you plan to do Sage development or otherwise work with + ticket branches and not only releases, install the bootstrapping + prerequisites. See the files in the folder [build/pkgs/_bootstrap/distros](build/pkgs/_bootstrap/distros), or visit https://doc.sagemath.org/html/en/reference/spkg/_bootstrap.html#spkg-bootstrap -5. [Git] If you cloned the Sage repository using `git`, bootstrap the - source tree using the following command: +7. Bootstrap the source tree using the following command: $ make configure - (If the bootstrapping prerequisites are not installed, this command will - download a package providing pre-built bootstrap output instead.) + (If the bootstrapping prerequisites are not installed, this command + will download a package providing pre-built bootstrap output instead.) -6. Sanitize the build environment. Use the command +8. Sanitize the build environment. Use the command $ env @@ -277,7 +291,7 @@ in the Installation Guide. can also add it to your shell profile so that it gets run automatically in all future sessions.) -7. Optionally, decide on the installation prefix (`SAGE_LOCAL`): +9. Optionally, decide on the installation prefix (`SAGE_LOCAL`): - Traditionally, and by default, Sage is installed into the subdirectory hierarchy rooted at `SAGE_ROOT/local/`. @@ -295,15 +309,11 @@ in the Installation Guide. installs (`make install` is a no-op). Therefore the installation hierarchy must be writable by the user. - - See the installation manual for options if you want to + - See the Sage Installation Manual for options if you want to install into shared locations such as `/usr/local/`. Do not attempt to build Sage as `root`. -8. Optional: It is recommended that you have both LaTeX and - the ImageMagick tools (e.g. the "convert" command) installed - since some plotting functionality benefits from them. - -9. Optionally, review the configuration options, which includes +10. Optionally, review the configuration options, which includes many optional packages: $ ./configure --help @@ -321,7 +331,7 @@ in the Installation Guide. a great speedup when switching between different branches, at the expense of disk space use. -10. Optional, but highly recommended: Set some environment variables to +11. Optional, but highly recommended: Set some environment variables to customize the build. For example, the `MAKE` environment variable controls whether to @@ -343,7 +353,7 @@ in the Installation Guide. building Sage, see [the installation guide](https://doc.sagemath.org/html/en/installation/source.html#environment-variables). -11. Type `./configure`, followed by any options that you wish to use. +12. Type `./configure`, followed by any options that you wish to use. For example, to build Sage with `gf2x` package supplied by Sage, use `./configure --with-system-gf2x=no`. @@ -363,60 +373,60 @@ in the Installation Guide. available; only the most recent releases of your distribution will have all of these recommended packages. -12. Optional: If you choose to install the additional system packages, +13. Optional: If you choose to install the additional system packages, a re-run of `./configure` will test whether the versions installed are usable for Sage; if they are, this will reduce the compilation time and disk space needed by Sage. The usage of packages may be adjusted by `./configure` parameters (check again the output of `./configure --help`). -13. Type `make`. That's it! Everything is automatic and +14. Type `make`. That's it! Everything is automatic and non-interactive. If you followed the above instructions, in particular regarding the installation of system packages recommended by the output of - `./configure` (step 10), and regarding the parallel build (step 9), + `./configure` (step 11), and regarding the parallel build (step 10), building Sage takes less than one hour on a modern computer. (Otherwise, it can take much longer.) The build should work fine on all fully supported platforms. If it does not, we want to know! -14. Type `./sage` to try it out. In Sage, try for example `2 + 2`, +15. Type `./sage` to try it out. In Sage, try for example `2 + 2`, `plot(x^2)`, `plot3d(lambda x, y: x*y, (-1, 1), (-1, 1))` to test a simple computation and plotting in 2D and 3D. Type Ctrl+D or `quit` to quit Sage. -15. Optional: Type `make ptestlong` to test all examples in the documentation +16. Optional: Type `make ptestlong` to test all examples in the documentation (over 200,000 lines of input!) -- this takes from 10 minutes to several hours. Don't get too disturbed if there are 2 to 3 failures, but always feel free to email the section of `logs/ptestlong.log` that contains errors to the [sage-support mailing list](https://groups.google.com/group/sage-support). If there are numerous failures, there was a serious problem with your build. -16. The HTML version of the [documentation](https://doc.sagemath.org/html/en/index.html) +17. The HTML version of the [documentation](https://doc.sagemath.org/html/en/index.html) is built during the compilation process of Sage and resides in the directory `local/share/doc/sage/html/`. You may want to bookmark it in your browser. -17. Optional: If you want to build the PDF version of the documentation, +18. Optional: If you want to build the PDF version of the documentation, run `make doc-pdf` (this requires LaTeX to be installed). -18. Optional: Install optional packages of interest to you: +19. Optional: Install optional packages of interest to you: get a list by typing `./sage --optional` or by visiting the [packages documentation page](https://doc.sagemath.org/html/en/reference/spkg/). -19. Optional: Create a symlink to the installed `sage` script in a - directory in your `PATH`, for example ``/usr/local``. This will +20. Optional: Create a symlink to the installed `sage` script in a + directory in your `PATH`, for example `/usr/local`. This will allow you to start Sage by typing `sage` from anywhere rather than having to either type the full path or navigate to the Sage directory and type `./sage`. This can be done by running: $ sudo ln -s $(./sage -sh -c 'ls $SAGE_ROOT/venv/bin/sage') /usr/local/bin -20. Optional: Set up SageMath as a Jupyter kernel in an existing Jupyter notebook +21. Optional: Set up SageMath as a Jupyter kernel in an existing Jupyter notebook or JupyterLab installation, as described in [section "Launching SageMath"](https://doc.sagemath.org/html/en/installation/launching.html) - in the installation manual. + in the Sage Installation Manual. Alternative Installation using PyPI --------------- @@ -505,7 +515,7 @@ Directory Layout Simplified directory layout (only essential files/directories): ``` -SAGE_ROOT Root directory (sage-x.y in Sage tarball) +SAGE_ROOT Root directory (create by git clone) ├── build │ └── pkgs Every package is a subdirectory here │ ├── 4ti2/ diff --git a/src/doc/en/developer/doctesting.rst b/src/doc/en/developer/doctesting.rst index f7c54bbbeec..e6324640ca1 100644 --- a/src/doc/en/developer/doctesting.rst +++ b/src/doc/en/developer/doctesting.rst @@ -26,7 +26,7 @@ this syntax: .. CODE-BLOCK:: text - /path/to/sage-x.y.z/sage -t [--long] /path/to/sage-x.y.z/path/to/module.py[x] + /path/to/sage_root/sage -t [--long] /path/to/sage_root/path/to/module.py[x] where ``--long`` is an optional argument (see :ref:`section-options` for more options). The version of ``sage`` used must match the version diff --git a/src/doc/en/developer/git_setup.rst b/src/doc/en/developer/git_setup.rst index f95b0d653da..bcd19a916a6 100644 --- a/src/doc/en/developer/git_setup.rst +++ b/src/doc/en/developer/git_setup.rst @@ -12,11 +12,9 @@ Installing Git Depending on your platform, use the following to install Git: -Debian / Ubuntu - Run ``sudo apt-get install git-core`` - -Fedora - Run ``sudo yum install git-core`` +Linux + See :ref:`spkg_git` for the installation command on your + Linux distribution. Windows (WSL) We strongly recommend to install the package using the Linux diff --git a/src/doc/en/developer/walkthrough.rst b/src/doc/en/developer/walkthrough.rst index 6e1b686989a..1faf7c271f2 100644 --- a/src/doc/en/developer/walkthrough.rst +++ b/src/doc/en/developer/walkthrough.rst @@ -61,8 +61,8 @@ Obtaining the Sage source code ============================== Obviously one needs the Sage source code to develop. You can use your -local installation of Sage, or (to start from scratch) download it -from our Sage repository on GitHub:: +local installation of Sage (if you installed Sage from source), or +(to start from scratch) download it from our Sage repository on GitHub:: [alice@localhost ~]$ git clone --origin upstream https://github.com/sagemath/sage.git Cloning into 'sage'... diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index 0732d028942..093d0ed9f26 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -373,9 +373,49 @@ Installation steps #. Follow the procedure in the file `README.md `_ in ``SAGE_ROOT``. +#. If you wish to prepare for having to build Sage in an environment + without sufficient Internet connectivity: + + - After running ``configure``, you can use ``make download`` to force + downloading packages before building. After this, the packages + are in the subdirectory ``upstream``. + + - Alternatively, instead of cloning the git repository, you + can download a self-contained release tarball for any + stable release from the Sage project's + `GitHub Releases `_. + Use the file named ``sage-x.y.tar.gz`` (1.25 GB as of Sage 10.2) + in the Release Assets, which contains a prepopulated subdirectory + ``upstream``. + + After downloading the source tarball ``sage-x.y.tar.gz`` into + a directory ``~/sage/``:: + + $ cd ~/sage/ + $ tar xf sage-x.y.tar.gz # adapt x.y; takes a while + + This creates the subdirectory ``sage-x.y``. Now change into it:: + + $ cd sage-x.y/ # adapt x.y + + .. note:: + + On Windows, it is crucial that you unpack the source tree from the + WSL `bash` using the WSL `tar` utility and not using other + Windows tools (including mingw). + + This is because the Sage source tree contains symbolic links, and the + build will not work if Windows line endings rather than UNIX + line endings are used. + + - The Sage mirrors also provide such self-contained tarballs + for all `stable releases `_ + and additionally for all `development releases + `_. + #. Additional remarks: You do not need to be logged in as root, since no files are - changed outside of the :file:`sage-x.y` directory. + changed outside of the :file:`SAGE_ROOT` directory. In fact, **it is inadvisable to build Sage as root**, as the root account should only be used when absolutely necessary and mistyped commands can have serious consequences if you are logged in as root. @@ -490,7 +530,7 @@ Installation steps - Make a symbolic link from :file:`/usr/local/bin/sage` (or another directory in your :envvar:`PATH`) to :file:`$SAGE_ROOT/sage`:: - $ ln -s /path/to/sage-x.y/sage /usr/local/bin/sage + $ ln -s /path/to/sage_root/sage /usr/local/bin/sage Now simply typing ``sage`` from any directory should be sufficient to run Sage.