Skip to content

Commit

Permalink
Trac #33088: More updates for installation and developer guides
Browse files Browse the repository at this point in the history
In this ticket:
- (from https://trac.sagemath.org/ticket/33426#comment:18) The link on
the index page still goes to the wiki, which should be probably changed
now that the relevant instructions are migrated.
​https://516701dbc7dd9738fb9d77ee3ac210c3919c8cb3--sagemath-
tobias.netlify.app/installation/index.html
- (follow up from #29784) Also should explain `configure --enable-
editable` (https://wiki.sagemath.org/ReleaseTours/sage-9.3#Editable_.28
.22in-place.22.2C_.22develop.22.29_installs_of_the_Sage_library)
- The "install from source" chapter of the installation manual could be
changed so that it points to README.md from the very beginning

See also:
- #33553 README Build from Source: m4 (step 5) is needed to run `make
configure` (step 3)
- #33426 add more details on conda-based installations of Sage
- #31342 Extend documentation on how to set up the virtual environment
- #33648 Update/reorder git instructions in Developer's Guide
- #33649 Developer's Guide: Update reviewer's check list from wiki
- #30484 Documentation/configuration for Sage on Windows using Visual
Studio (vscode) with a WSL remote
- #33662 Installation guide: Change "install from source" chapter so
that it only provides extra detail in the same order as README.md

URL: https://trac.sagemath.org/33088
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe, Yuan Zhou
Reviewer(s): Dima Pasechnik
  • Loading branch information
Release Manager committed Apr 19, 2022
2 parents b5a7bd1 + 8716d80 commit 79dc3df
Show file tree
Hide file tree
Showing 8 changed files with 123 additions and 113 deletions.
117 changes: 78 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,14 @@ for modules and functions list the authors.
Getting Started
---------------

If you downloaded a [binary](https://www.sagemath.org/download.html)
(i.e. a version of SageMath prepared for a specific operating system),
Sage is ready to start -- just open a terminal in the directory where
you extracted the binary archive and type:
The [Sage Installation Guide](https://doc.sagemath.org/html/en/installation/index.html)
provides a decision tree that guides you to the type of installation
that will work best for you.

$ ./sage

(Note that the first run will take more time, as Sage needs to get itself ready.)

If you downloaded the [sources](https://www.sagemath.org/download-source.html),
please read below on how to build Sage and work around common issues.
If you have already cloned the git repository or downloaded the
[sources](https://www.sagemath.org/download-source.html) in the form
of a tarball, please read the self-contained instructions below on how
to build Sage and work around common issues.

If you have questions or encounter problems, please do not hesitate
to email the [sage-support mailing list](https://groups.google.com/group/sage-support)
Expand All @@ -39,7 +36,7 @@ Supported Platforms
-------------------

Sage attempts to support all major Linux distributions, recent versions of
macOS, and Windows (using Cygwin, Windows Subsystem for Linux, or
macOS, and Windows (using Windows Subsystem for Linux, Cygwin, or
virtualization).

Detailed information on supported platforms for a specific version of Sage
Expand All @@ -62,8 +59,17 @@ and follow the instructions on
[Windows] Preparing the Platform
--------------------------------

The 64-bit version of Cygwin, also known as Cygwin64, is the current
target for Sage support on Windows.
The preferred way to run Sage on Windows is using the [Windows Subsystem for
Linux](https://docs.microsoft.com/en-us/windows/wsl/faq), which allows
you to install a standard Linux distribution such as Ubuntu within
your Windows. Then all instructions for installation in Linux apply.

As an alternative, you can also run Linux on Windows using Docker (see
above) or other virtualization solutions.

Finally, Sage also works on the 64-bit version of `Cygwin
<https://cygwin.com/>`_. If you wish to use Cygwin, use the following
instructions to get started.

1. Download [cygwin64](https://cygwin.com/install.html) (do not get
the 32-bit version; it is not supported by Sage).
Expand Down Expand Up @@ -112,32 +118,42 @@ target for Sage support on Windows.
$ install apt-cyg /usr/local/bin
$ rm -f apt-cyg

An alternative to Cygwin is to use [Windows Subsystem for
Linux](https://docs.microsoft.com/en-us/windows/wsl/faq), which allows
you to install a standard Linux distribution such as Ubuntu within
your Windows. Then all instructions for installation in Linux apply.

As another alternative, you can also run Linux on Windows using Docker
(see above) or other virtualization solutions.

[macOS] Preparing the Platform
------------------------------

Make sure you have installed the most current version of Xcode
supported on your version of macOS. If you don't, either go to
https://developer.apple.com/, sign up, and download the free Xcode
package, or get it from Apple's app store.
If your Mac uses the Apple Silicon (M1, arm64) architecture:

- If you set up your Mac by transfering files from an older Mac, make sure
that the directory ``/usr/local`` does not contain an old copy of Homebrew
(or other software) for the x86_64 architecture that you may have copied
over. Note that Homebrew for the M1 is installed in ``/opt/homebrew``, not
``/usr/local``.

- If you wish to use conda, please see the [section on
conda](https://doc.sagemath.org/html/en/installation/conda.html) in the Sage
Installation Manual for guidance.

- Otherwise, using Homebrew ("the missing package manager for macOS") from
https://brew.sh/ required because it provides a version of ``gfortran`` with
necessary changes for this platform that are not in a released upstream
version of GCC. (The ``gfortran`` package that comes with the Sage
distribution is not suitable for the M1.)

If your Mac uses the Intel (x86_64) architecture:

- If you wish to use conda, please see the [section on
conda](https://doc.sagemath.org/html/en/installation/conda.html) in the Sage
Installation Manual for guidance.

You also need to install the "command line tools": After installing
Xcode, run `xcode-select --install` from a terminal window; then click
"Install" in the pop-up window. (When using Mountain Lion or earlier,
you need to install the command line tools from Xcode: run Xcode; then
from the File menu, choose "Preferences", then the "Downloads" tab,
and then "Install" the Command Line Tools.)
- Otherwise, we strongly recommend to use Homebrew ("the missing package
manager for macOS") from https://brew.sh/, which provides the ``gfortran``
compiler and many libraries.

Optionally, you can consider installing Homebrew ("the missing package
manager for macOS") from https://brew.sh/, which can provide libraries
such as `gfortran`, `gmp`, etc.
- Otherwise, if you do not wish to install Homebrew, you will need to install
the latest version of Xcode Command Line Tools. Open a terminal window and
run `xcode-select --install`; then click "Install" in the pop-up window. If
the Xcode Command Line Tools are already installed, you may want to check if
they need to be updated by typing `softwareupdate -l`.

Instructions to Build from Source
---------------------------------
Expand Down Expand Up @@ -180,7 +196,7 @@ in the Installation Guide.
- [Cygwin] Avoid building in home directories of Windows domain
users or in paths with capital letters.

2. Download/unpack the sources.
2. Download/unpack or clone the sources.

- Go to https://www.sagemath.org/download-source.html, select a mirror,
and download the file :file:`sage-x.y.tar.gz`.
Expand All @@ -198,12 +214,16 @@ in the Installation Guide.

$ cd sage-x.y/ # adapt x.y

- [Git] Alternatively, clone the Sage git repository:
- [Git] Alternatively, and required for Sage development, clone the Sage
git repository:

$ ORIG=https://github.com/sagemath/sage.git
$ git clone -c core.symlinks=true --branch develop --tags $ORIG

This will create the directory `sage`.
This will create the directory `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:
Expand Down Expand Up @@ -231,8 +251,8 @@ in the Installation Guide.
``ExtUtils::MakeMaker``), `ranlib`, `git`, `tar`, `bc`.

- Python 3.4 or later, or Python 2.7, a full installation including
`urllib`; but ideally version 3.7.x, 3.8.x, or 3.9.x, which will
avoid having to build Sage's own copy of Python 3.
`urllib`; but ideally version 3.7.x, 3.8.x, 3.9.x, or 3.10.x, which
will avoid having to build Sage's own copy of Python 3.

We have collected lists of system packages that provide these build
prerequisites. See, in the folder
Expand Down Expand Up @@ -290,6 +310,25 @@ in the Installation Guide.

$ ./configure --help

Some notable options for Sage developers are the following:

- Use `./configure --enable-editable` to configure the Sage distribution
to install the Sage library in "develop" ("editable", "in-place") mode
instead of using the Sage library's custom incremental build system.

It has the benefit that to try out changes to Python files, one does not
need to run `./sage -b` any more; restarting Sage is enough. It may also
have benefits in certain develop environments that get confused by
sagelib's custom build system.

Note that in an editable install, the source directory will be cluttered
with build artifacts (but they are `.gitignored`). This is normal.

- Use `./configure --enable-download-from-upstream-url` to allow
downloading packages from their upstream URL if they cannot (yet) be
found on the Sage mirrors. This is useful for trying out ticket branches
that make package upgrades.

9. Optional, but highly recommended: Set some environment variables to
customize the build.

Expand Down
2 changes: 1 addition & 1 deletion src/doc/en/developer/coding_basics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1283,7 +1283,7 @@ whitespace, see https://www.emacswiki.org/emacs/DeletingWhitespace
for various solutions.

If you use another editor, we recommend to configure it so you do not
add tabs to files.
add tabs to files. See :ref:`section-ide`.


Global Options
Expand Down
2 changes: 1 addition & 1 deletion src/doc/en/developer/tools.rst
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ The tox configuration ``SAGE_ROOT/src/tox.ini`` can be invoked by using the comm
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`` so see what is
known as "tox environments". We can type ``./sage --advanced`` to see what is
available::

$ ./sage --advanced
Expand Down
4 changes: 2 additions & 2 deletions src/doc/en/developer/walk_through.rst
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ Sage source code and which you can upload to trac tickets.

To begin with, type the command ``git branch``. You will see the following::

[user@localhost]$ git branch
[user@localhost sage]$ git branch
* develop
master

Expand Down Expand Up @@ -144,7 +144,7 @@ to it. For this, you have to use ``git checkout``::

Now if you use the command ``git branch``, you will see the following::

[user@localhost]$ git branch
[user@localhost sage]$ git branch
develop
* last_twin_prime
master
Expand Down
11 changes: 10 additions & 1 deletion src/doc/en/developer/workspace.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,19 @@
Setting up your workspace
=========================

.. _section-ide:

Configuring text editors and IDEs for use with Sage
===================================================

In Meta-ticket :trac:`30500` we are collecting instructions how to configure
various text editors and IDEs for use with Sage.


.. _section-gitpod:

Gitpod
=================
======

`Gitpod <https://www.gitpod.io>`_ is a free service that will let you build and
run Sage from an online development environment based on VS Code.
Expand Down
7 changes: 7 additions & 0 deletions src/doc/en/installation/conda.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ which uses a faster dependency solver than `conda`.
conda install mamba
.. _sec-installation-conda-binary:

Installing all of SageMath from conda (not for development)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -45,6 +47,8 @@ To use Sage from there,
* Start SageMath: ``sage``


.. _sec-installation-conda-source:

Using conda to provide system packages for the Sage distribution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -75,6 +79,9 @@ prepare for installing SageMath from source:
$ ./configure --prefix=$CONDA_PREFIX
$ make


.. _sec-installation-conda-develop:

Using conda to provide all dependencies for the Sage library (experimental)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down
8 changes: 4 additions & 4 deletions src/doc/en/installation/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ SageMath release.
- Then build SageMath from source as described in section
:ref:`sec-installation-from-sources`.

- Alternatively, follow the instructions in the SageMath wiki on
`Conda for Sage Developers <https://wiki.sagemath.org/Conda>`_;
- Alternatively, follow the instructions in section
:ref:`sec-installation-conda-develop`;
these describe an experimental method that gets all required
packages, including Python packages, from conda-forge.

Expand Down Expand Up @@ -67,8 +67,8 @@ SageMath release.
- Then build SageMath from source as described in section
:ref:`sec-installation-from-sources`.

- Alternatively, follow the instructions in the SageMath wiki on
`Conda for Sage Developers <https://wiki.sagemath.org/Conda>`_;
- Alternatively, follow the instructions in section
:ref:`sec-installation-conda-develop`;
these describe an experimental method that gets all required
packages, including Python packages, from conda-forge.

Expand Down
Loading

0 comments on commit 79dc3df

Please sign in to comment.