trac 29558: first draft

Author: jhpalmieri

src/doc/bootstrap

@@ -23,7 +23,7 @@ mkdir -p "$OUTPUT_DIR"
 
 shopt -s extglob
 
-for SYSTEM in arch debian fedora cygwin; do
+for SYSTEM in arch debian fedora cygwin homebrew; do
     SYSTEM_PACKAGES=$(echo $(${STRIP_COMMENTS} build/pkgs/$SYSTEM.txt))
     for PKG_SCRIPTS in build/pkgs/*; do
         if [ -d $PKG_SCRIPTS ]; then

src/doc/en/installation/source.rst

@@ -228,6 +228,13 @@ On Debian ("buster" or newer) or Ubuntu ("bionic" or newer):
 
 .. literalinclude:: debian.txt
 
+.. WARNING::
+
+     Note: in this documentation, commands like these are
+     autogenerated. They may as such include duplications. The
+     duplications are certainly not necessary for the commands to
+     function properly, but they don't cause any harm, either.
+
 On Fedora / Redhat / CentOS:
 
 .. literalinclude:: fedora.txt
@@ -297,6 +304,43 @@ a registration.
   to Command Line Tools.
 
 
+
+macOS recommended installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Although Sage can in theory build its own version of gfortran, this
+can take a while, and the process fails on some recent versions of
+OS X. So instead you can install your own copy. One advantage of this
+is that you can install it once, and it will get used every time you
+build Sage, rather than building gfortran every time.
+
+One way to do that is with the `Homebrew package manager
+<https://brew.sh>`_. Install Homebrew as their web page describes, and
+then the command ::
+
+    $ brew install gcc
+
+will install Homebrew's gcc package, which includes gfortran. Sage
+will also use other Homebrew packages, if they are present. You can
+install the following:
+
+.. literalinclude:: homebrew.txt
+
+Some Homebrew packages are installed "keg-only," meaning that they are
+not available in standard paths. To make them accessible when building
+Sage, run ::
+
+    $ source SAGE_ROOT/.homebrew-build-env
+
+(replacing ``SAGE_ROOT`` by Sage's home directory). You can add a
+command like this to your shell profile if you want the settings to
+persist between shell sessions.
+
+Some additional optional packages are taken care of by:
+
+.. literalinclude:: homebrew-optional.txt
+
+
 .. _section_cygwinprereqs:
 
 Cygwin prerequisite installation