#16273 closed enhancement (fixed)
update README
Reported by:  vbraun  Owned by:  

Priority:  blocker  Milestone:  sage6.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
 Branch set to u/vbraun/update_readme
comment:2 Changed 7 years ago by
 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
comment:3 Changed 7 years ago by
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 sagedevel 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/r3.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
 Status changed from needs_review to needs_work
comment:5 Changed 7 years ago by
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 followup: ↓ 8 Changed 7 years ago by
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
 Commit changed from bffa8acc4f7638128ef03435c71ec6cdb444bfcc to d60e5d7a028727f0ca7f66504dc7bfe9e06c6978
Branch pushed to git repo; I updated commit sha1. New commits:
d60e5d7  reviewer changes

comment:8 in reply to: ↑ 6 Changed 7 years ago by
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
The build directory is documented (somewhat) in the installation guide, but it's outofdate: look at http://www.sagemath.org/doc/installation/source.html#environmentvariables, 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
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: 886 886 and uses more memory and disk space than using MathJax. 887 887 888 888  :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 890 891 :file:`atlas3.8.3.p12.spkg` in the directory 891 :file:`$SAGE_ROOT/ spkg/build/atlas3.8.3.p12/`.892 :file:`$SAGE_ROOT/local/var/tmp/sage/build/atlas3.8.3.p12/`. 892 893 If this variable is set, then build in 893 894 :file:`$SAGE_BUILD_DIR/atlas3.8.3.p12/` instead. 894 895 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: 909 910 910 911  :envvar:`SAGE_KEEP_BUILT_SPKGS`  the default behavior is to delete each 911 912 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 913 915 is successfully built, and to keep it if there were errors installing the 914 916 spkg. 915 917 Set this variable to ``yes`` to keep the subdirectory regardless. … … Here are some of the more commonly used variables affecting the build process: 917 919 corresponding subdirectory, for example left over from a previous build, 918 920 then the default behavior is to delete that old subdirectory. 919 921 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`), 921 924 overwriting any already existing file or directory with the same name. 922 925 923 926 .. note:: … … Sage uses the following environment variables when it runs: 1106 1109 If you wish to set up your own server, then note that Sage will search the 1107 1110 directories: 1108 1111 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/`` 1113 1116 1114 1117 for packages. 1115 See the script :file:`$SAGE_ROOT/s pkg/bin/sagespkg` for the implementation.1118 See the script :file:`$SAGE_ROOT/src/bin/sagespkg` for the implementation. 1116 1119 1117 1120  :envvar:`SAGE_PATH`  a colonseparated list of directories which Sage 1118 1121 searches when trying to locate Python libraries. … … Sage uses the following environment variables when it runs: 1129 1132 set the :envvar:`DYLD_LIBRARY_PATH` variable. 1130 1133 1131 1134  :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`. 1133 1136 Set this to the base name of the BLAS library file on your system if you want 1134 1137 to override the default setting. 1135 1138 That is, if the relevant file is called :file:`libcblas_new.so` or … … Variables dealing with doctesting: 1159 1162 jar, set this to something nonempty and run the doctest suite. 1160 1163 See the documentation for the functions :func:`picklejar` and 1161 1164 :func:`unpickle_all` in 1162 :file:`$SAGE_ROOT/ devel/sage/sage/structure/sage_object.pyx`, online1165 :file:`$SAGE_ROOT/src/sage/structure/sage_object.pyx`, online 1163 1166 `here (picklejar) 1164 1167 <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.picklejar>`_ 1165 1168 and `here (unpickle_all) … … would be appropriate if you have a Core i3/5/7 processor with AVX support. 1287 1290 1288 1291 1289 1292 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
John: sounds good to me, are you going to push your branch?
comment:12 Changed 7 years ago by
 Priority changed from major to blocker
comment:13 Changed 7 years ago by
 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:
ce472ee  Update toplevel README.txt and installation guide

comment:14 Changed 7 years ago by
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
 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
 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
 Commit ce472ee80d2f5a6983852be17417640bb0074fb1 deleted
Did anything here help with #5505? Just askin'.
New commits:
updated readme