Opened 13 years ago

Closed 5 years ago

#3131 closed defect (fixed)

README and developer guide should warn against developing with binaries

Reported by: mabshoff Owned by: btdhall
Priority: minor Milestone: sage-7.3
Component: documentation Keywords: beginner
Cc: Merged in:
Authors: Bryton T.D. Hall Reviewers: Paul Masson
Report Upstream: N/A Work issues:
Branch: 3958013 (Commits, GitHub, GitLab) Commit: 39580132732a5c0319ecd01fc0f1bd136f537a01
Dependencies: Stopgaps:

Status badges

Description (last modified by mmezzarobba)

Aside from that it is *highly*
recommended to build from source if you are developing since mixing
and matching different compiler releases [even on OSX] can lead to odd
results, i.e. Heisenbugs and segfaults.

Cheers,

Michael

Change History (28)

comment:1 Changed 13 years ago by mabshoff

  • Owner changed from tba to mabshoff
  • Status changed from new to assigned

Maybe this should go into "Section 7.1 of the Sage Programming Guide" instead.

Cheers,

Michael

comment:2 Changed 8 years ago by jdemeyer

  • Milestone changed from sage-5.11 to sage-5.12

comment:3 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.1 to sage-6.2

comment:4 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.2 to sage-6.3

comment:5 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.3 to sage-6.4

comment:6 Changed 7 years ago by aapitzsch

  • Milestone changed from sage-6.4 to sage-duplicate/invalid/wontfix
  • Report Upstream set to N/A
  • Status changed from new to needs_review

This became invalid when we switched to git.

comment:7 follow-up: Changed 7 years ago by kcrisman

  • Status changed from needs_review to needs_info

Hmm, good point! I just saw this too. Are there any instructions we need to give people about how to develop with binaries? (Such as, you really need to build from scratch.) Maybe this is already in the much-underused installation guide...

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

Replying to kcrisman:

Are there any instructions we need to give people about how to develop with binaries? (Such as, you really need to build from scratch.)

Exactly: "don't do it" is the best advice you can give.

comment:9 Changed 7 years ago by kcrisman

  • Milestone changed from sage-duplicate/invalid/wontfix to sage-6.4
  • Status changed from needs_info to needs_work
  • Summary changed from README.txt: update recommendations for dev work with binaries to README and developer guide warn against developing with binaries

Then what I would say is to make this really loud somewhere correct. The problem is that some stuff in the install guide should really be in the developer guide, as there isn't much about sage -b anywhere in there as far as I can tell (maybe in the git sections?).

comment:10 Changed 6 years ago by kcrisman

  • Keywords beginner added
  • Summary changed from README and developer guide warn against developing with binaries to README and developer guide should warn against developing with binaries

comment:11 Changed 6 years ago by mmezzarobba

  • Milestone changed from sage-6.4 to sage-duplicate/invalid/wontfix
  • Status changed from needs_work to positive_review

comment:12 follow-ups: Changed 6 years ago by kcrisman

  • Status changed from positive_review to needs_info

Why would this be wontfix? Have we already said very loudly "don't do it"?

comment:13 in reply to: ↑ 12 Changed 6 years ago by mmezzarobba

  • Description modified (diff)
  • Status changed from needs_info to needs_work

Replying to kcrisman:

Why would this be wontfix? Have we already said very loudly "don't do it"?

Oops, sorry, I had the same reaction as you about this becoming meaningless with the switch to git, and I did not notice the recent discussion.

comment:14 in reply to: ↑ 12 Changed 6 years ago by jdemeyer

Replying to kcrisman:

Have we already said very loudly "don't do it"?

Is there a reason why people shouldn't do it? Since when did we stop supporting developing with binaries?

comment:15 Changed 6 years ago by kcrisman

You said it! comment:8

Exactly: "don't do it" is the best advice you can give.

If not, then we should say just what prereqs and problems might be necessary/arise.

comment:16 Changed 6 years ago by jdemeyer

Funny :-)

Maybe there is a good reason that I currently cannot think of.

comment:17 Changed 6 years ago by kcrisman

Well, the obvious reason is that people keep trying to do it and then failing because they don't have gcc or some other prereq, or because of some hard-coded paths that screw things up from the buildbot. However, maybe saying that people need to be extra-special careful in that event is enough...?

comment:18 Changed 5 years ago by kcrisman

So, where do we say "don't do this", if at all?

Last edited 5 years ago by kcrisman (previous) (diff)

comment:19 Changed 5 years ago by btdhall

On the index of the Developer's Guide (http://doc.sagemath.org/html/en/developer/index.html) it mentions needing the source code which implies that you can't develop from only a binary.

I think that should be sufficient but maybe we need to direct users in README.md to "read the Developer's Guide" if they would like to contribute. This is already the advice given in the "Development" link on the main website (http://www.sagemath.org/development.html) as well as the contributing FAQ (http://doc.sagemath.org/html/en/faq/faq-contribute.html) where it also says to "...grab a copy of the Sage source...".

So, if anything, we can change the wording in the Developer's Guide to be less suggestive since that's where all roads to getting started in development should lead.

comment:20 Changed 5 years ago by btdhall

  • Branch set to u/btdhall/ticket_3131
  • Milestone changed from sage-duplicate/invalid/wontfix to sage-7.3
  • Owner changed from mabshoff to btdhall
  • Priority changed from major to minor

comment:21 Changed 5 years ago by btdhall

  • Branch u/btdhall/ticket_3131 deleted

comment:22 Changed 5 years ago by btdhall

  • Branch set to u/btdhall/readme_and_developer_guide_should_warn_against_developing_with_binaries

comment:23 Changed 5 years ago by btdhall

  • Commit set to 6c2f8aaba1f510b11e4ccc90c3fa05fbf5c85a64
  • Status changed from needs_work to needs_review

New commits:

6c2f8aaAdd link in README.md to Developer's Guide.

comment:24 Changed 5 years ago by paulmasson

@btdhall while you're touching this file, there are two occurrences of sagemath.org/doc/ and two occurrences of www.sagemath.org/doc/ that should all be changed to doc.sagemath.org/html/en/.

I've been trying to help Harald Schilly to get Google to stop indexing the old documentation location and it doesn't help if it's there on the default GitHub page.

comment:25 Changed 5 years ago by git

  • Commit changed from 6c2f8aaba1f510b11e4ccc90c3fa05fbf5c85a64 to 39580132732a5c0319ecd01fc0f1bd136f537a01

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

3958013Fixed four broken links to documentation.

comment:26 follow-up: Changed 5 years ago by paulmasson

  • Reviewers set to Paul Masson
  • Status changed from needs_review to positive_review

Looks good. Thanks!

comment:27 in reply to: ↑ 26 Changed 5 years ago by btdhall

  • Authors set to Bryton T.D. Hall

Replying to paulmasson:

Looks good. Thanks!

No problem.

While we're on the topic, the errata (http://wiki.sagemath.org/errata) links to an empty wiki page but I couldn't find the proper location. Let me know if you have a suggestion for fixing it.

comment:28 Changed 5 years ago by vbraun

  • Branch changed from u/btdhall/readme_and_developer_guide_should_warn_against_developing_with_binaries to 39580132732a5c0319ecd01fc0f1bd136f537a01
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.