Opened 7 years ago

Closed 7 years ago

Last modified 7 years ago

#16273 closed enhancement (fixed)

update README

Reported by: vbraun Owned by:
Priority: blocker Milestone: sage-6.2
Component: documentation Keywords:
Cc: Merged in:
Authors: Volker Braun, John Palmieri Reviewers: William Stein, Volker Braun
Report Upstream: N/A Work issues:
Branch: ce472ee (Commits) Commit:
Dependencies: Stopgaps:

Description


Change History (17)

comment:1 Changed 7 years ago by vbraun

  • Branch set to u/vbraun/update_readme

comment:2 Changed 7 years ago by vbraun

  • Authors set to Volker Braun
  • Commit set to bffa8acc4f7638128ef03435c71ec6cdb444bfcc
  • Component changed from PLEASE CHANGE to documentation
  • Status changed from new to needs_review
  • Type changed from PLEASE CHANGE to enhancement

New commits:

bffa8acupdated readme

comment:3 Changed 7 years ago by was

Fantastic! Here's a few very small remarks/typos (see below). Once addressed, this should get a positive review.

  • Could we change "6. OPTIONAL: Type "make ptest" to test all examples in the documentation (over 93,000 lines of input!)" to "6. OPTIONAL: Type "make ptest" to test all examples in the documentation (over 200,000 lines of input!)", since:
/usr/local/sage/current/src/sage$ grep -r sage: * | grep -v \.c: | grep -v \.cpp | wc -l
212574
  • "First, install OpenSSL and the OpenSSL development headers on your system if they are not already." --> "First, install OpenSSL and the OpenSSL development headers on your system if they are not already installed."
  • "install.log Full intall log" -> "install.log Full install log"
  • I'm glad there is a "DIRECTORY LAYOUT" section. It's not quite perfect, though. For example, my first question to sage-devel is "where is the temporary build directory when installing packages? (used to be spkg/build)". Looking at DIRECTORY LAYOUT one finds that SAGE_ROOT/tmp is described as "Temporary files when building Sage", which suggests that should be the answer to my question. However, it just isn't, since, e.g., R is built in "local/var/tmp/sage/build/r-3.0.2.p1". And there's no symlink involved here either. This question isn't answered either: "where are the databases? (used to be data/)".

comment:4 Changed 7 years ago by was

  • Status changed from needs_review to needs_work

comment:5 Changed 7 years ago by vbraun

I just don't think that many people want to hear where temporary files are during build. If something goes wrong then the error log already tells you where to go to try to fix it up.

comment:6 follow-up: Changed 7 years ago by ohanar

I actually don't think SAGE_ROOT/tmp is used in the build process (anymore?). At least I don't recall seeing anything about it (other than its creation) when working on the git transition.

comment:7 Changed 7 years ago by git

  • Commit changed from bffa8acc4f7638128ef03435c71ec6cdb444bfcc to d60e5d7a028727f0ca7f66504dc7bfe9e06c6978

Branch pushed to git repo; I updated commit sha1. New commits:

d60e5d7reviewer changes

comment:8 in reply to: ↑ 6 Changed 7 years ago by vbraun

Replying to ohanar:

I actually don't think SAGE_ROOT/tmp is used in the build process

Agree, seems to be unnecessary.

comment:9 Changed 7 years ago by jhpalmieri

The build directory is documented (somewhat) in the installation guide, but it's out-of-date: look at http://www.sagemath.org/doc/installation/source.html#environment-variables, under SAGE_BUILD_DIR and also SAGE_KEEP_BUILT_SPKGS. (The discussion of the variable SAGE_SERVER also refers to the spkg directory, by the way, and there are two references to the devel directory.) That should be fixed, too. Here? Another ticket?

comment:10 Changed 7 years ago by jhpalmieri

Here are some suggested changes to the installation guide.

  • src/doc/en/installation/source.rst

    diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst
    index a848cc2..a7d2c2b 100644
    a b Here are some of the more commonly used variables affecting the build process: 
    886886  and uses more memory and disk space than using MathJax.
    887887
    888888- :envvar:`SAGE_BUILD_DIR` - the default behavior is to build each spkg in a
    889   subdirectory of :file:`$SAGE_ROOT/spkg/build/`; for example, build
     889  subdirectory of :file:`$SAGE_ROOT/local/var/tmp/sage/build/`; for
     890  example, build
    890891  :file:`atlas-3.8.3.p12.spkg` in the directory
    891   :file:`$SAGE_ROOT/spkg/build/atlas-3.8.3.p12/`.
     892  :file:`$SAGE_ROOT/local/var/tmp/sage/build/atlas-3.8.3.p12/`.
    892893  If this variable is set, then build in
    893894  :file:`$SAGE_BUILD_DIR/atlas-3.8.3.p12/` instead.
    894895  If the directory :file:`$SAGE_BUILD_DIR` does not exist, it is created.
    Here are some of the more commonly used variables affecting the build process: 
    909910
    910911- :envvar:`SAGE_KEEP_BUILT_SPKGS` - the default behavior is to delete each
    911912  build directory -- the appropriate subdirectory of
    912   :file:`$SAGE_ROOT/spkg/build` or :file:`$SAGE_BUILD_DIR` -- after each spkg
     913  :file:`$SAGE_ROOT/local/var/tmp/sage/build` or
     914  :file:`$SAGE_BUILD_DIR` -- after each spkg
    913915  is successfully built, and to keep it if there were errors installing the
    914916  spkg.
    915917  Set this variable to ``yes`` to keep the subdirectory regardless.
    Here are some of the more commonly used variables affecting the build process: 
    917919  corresponding subdirectory, for example left over from a previous build,
    918920  then the default behavior is to delete that old subdirectory.
    919921  If this variable is set to ``yes``, then the old subdirectory is moved to
    920   :file:`$SAGE_ROOT/spkg/build/old/` (or :file:`$SAGE_BUILD_DIR/old`),
     922  :file:`$SAGE_ROOT/local/var/tmp/sage/build/old/`
     923  (or :file:`$SAGE_BUILD_DIR/old`),
    921924  overwriting any already existing file or directory with the same name.
    922925
    923926  .. note::
    Sage uses the following environment variables when it runs: 
    11061109  If you wish to set up your own server, then note that Sage will search the
    11071110  directories:
    11081111
    1109   - ``SAGE_SERVER/packages/standard/``,
    1110   - ``SAGE_SERVER/packages/optional/``,
    1111   - ``SAGE_SERVER/packages/experimental/``,
    1112   - and ``SAGE_SERVER/packages/archive/``
     1112  - ``SAGE_SERVER/spkg/standard/``,
     1113  - ``SAGE_SERVER/spkg/optional/``,
     1114  - ``SAGE_SERVER/spkg/experimental/``,
     1115  - and ``SAGE_SERVER/spkg/archive/``
    11131116
    11141117  for packages.
    1115   See the script :file:`$SAGE_ROOT/spkg/bin/sage-spkg` for the implementation.
     1118  See the script :file:`$SAGE_ROOT/src/bin/sage-spkg` for the implementation.
    11161119
    11171120- :envvar:`SAGE_PATH` - a colon-separated list of directories which Sage
    11181121  searches when trying to locate Python libraries.
    Sage uses the following environment variables when it runs: 
    11291132  set the :envvar:`DYLD_LIBRARY_PATH` variable.
    11301133
    11311134- :envvar:`SAGE_CBLAS` - used in the file
    1132   :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`.
     1135  :file:`SAGE_ROOT/src/sage/misc/cython.py`.
    11331136  Set this to the base name of the BLAS library file on your system if you want
    11341137  to override the default setting.
    11351138  That is, if the relevant file is called :file:`libcblas_new.so` or
    Variables dealing with doctesting: 
    11591162  jar, set this to something non-empty and run the doctest suite.
    11601163  See the documentation for the functions :func:`picklejar` and
    11611164  :func:`unpickle_all` in
    1162   :file:`$SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online
     1165  :file:`$SAGE_ROOT/src/sage/structure/sage_object.pyx`, online
    11631166  `here (picklejar)
    11641167  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.picklejar>`_
    11651168  and `here (unpickle_all)
    would be appropriate if you have a Core i3/5/7 processor with AVX support. 
    12871290
    12881291
    12891292
    1290 **This page was last updated in October 2013 (Sage 5.12).**
     1293**This page was last updated in May 2014 (Sage 6.2).**

There are other parts which are probably outdated:

  As of this writing (Sage 4.8), when building the standard Sage packages,
  1.5 gigabytes of free space are required in this directory (or more if
  ``SAGE_KEEP_BUILT_SPKGS=yes`` -- see below); the exact amount of required
  space varies from platform to platform.

and

      After a full build of Sage (as of version 4.8), these subdirectories can
      take up to 6 gigabytes of storage, in total, depending on the platform
      and the block size of the file system.

I don't know what these storage requirements should be now, but it's not as important as the other changes being discussed here.

comment:11 Changed 7 years ago by vbraun

John: sounds good to me, are you going to push your branch?

comment:12 Changed 7 years ago by vbraun

  • Priority changed from major to blocker

comment:13 Changed 7 years ago by jhpalmieri

  • Branch changed from u/vbraun/update_readme to u/jhpalmieri/readme
  • Commit changed from d60e5d7a028727f0ca7f66504dc7bfe9e06c6978 to ce472ee80d2f5a6983852be17417640bb0074fb1

Okay, here are my changes. Does this still need work, or have the issues been fixed?


New commits:

ce472eeUpdate top-level README.txt and installation guide

comment:14 Changed 7 years ago by jhpalmieri

Sorry, I'm still not used to git. I thought my branch would include Volker's original changes, but it didn't. What should I have done differently?

comment:15 Changed 7 years ago by vbraun

  • Authors changed from Volker Braun to Volker Braun, John Palmieri
  • Reviewers set to William Stein, Volker Braun
  • Status changed from needs_work to positive_review

No, you did everything correctly. Your commit is on top of mine...

comment:16 Changed 7 years ago by vbraun

  • Branch changed from u/jhpalmieri/readme to ce472ee80d2f5a6983852be17417640bb0074fb1
  • Resolution set to fixed
  • Status changed from positive_review to closed

comment:17 Changed 7 years ago by kcrisman

  • Commit ce472ee80d2f5a6983852be17417640bb0074fb1 deleted

Did anything here help with #5505? Just askin'.

Note: See TracTickets for help on using tickets.