| 486 | Environment variables |
| 487 | --------------------- |
| 488 | |
| 489 | Sage uses several environment variables to control its build process. |
| 490 | Most users won't need to use any of these: the build process just |
| 491 | works on many platforms. Building Sage involves building about 100 |
| 492 | packages, each of which has its own compilation instructions. |
| 493 | |
| 494 | Here are some of the more commonly used variables affecting the build |
| 495 | process: |
| 496 | |
| 497 | - :envvar:`MAKE` - one common setting for this variable when building |
| 498 | Sage is ``export MAKE='make -jNUM'`` to tell the "make" program to |
| 499 | run NUM jobs in parallel when building individual packages. (Not |
| 500 | all packages support this, but the ones for which this could be |
| 501 | problematic should automatically disable it.) |
| 502 | |
| 503 | - :envvar:`SAGE_CHECK` - if this is set to "yes", then during the |
| 504 | build process, run the test suite for each package which has one. |
| 505 | |
| 506 | - :envvar:`SAGE_PARALLEL_SPKG_BUILD` - set this to "yes" to build |
| 507 | multiple packages in parallel. This only has an effect if |
| 508 | :envvar:`MAKE` is also set to run several jobs in parallel. As of |
| 509 | this writing (June 2010), this is still in the experimental stages, |
| 510 | but turning this on can greatly speed up the build process. |
| 511 | |
| 512 | - :envvar:`SAGE64` - Set this to "yes" to build a 64-bit binary. This |
| 513 | is required if you want a 64-bit binary but the default for your |
| 514 | platform is to build 32-bit binaries. It adds the compiler flag |
| 515 | -m64 when compiling programs. The SAGE64 variable is mainly of use |
| 516 | is on OS X (pre 10.6), Solaris and OpenSolaris, though it will add |
| 517 | the -m64 on any operating system. If you are running version 10.6 of |
| 518 | OS X on a 64-bit machine, then Sage will automatically build a |
| 519 | 64-bit binary, so this variable does not need setting. |
| 520 | |
| 521 | - :envvar:`SAGE_FORTRAN` - see above, the "Fortran" section. |
| 522 | |
| 523 | - :envvar:`SAGE_FORTRAN_LIB` - see above, the "Fortran" section. |
| 524 | |
| 525 | - :envvar:`SAGE_DEBUG` - about half a dozen Sage packages use this |
| 526 | variable. If it is unset (the default) or set to "yes", then |
| 527 | debugging is turned on. If it is set to anything else, then |
| 528 | debugging is turned off. |
| 529 | |
| 530 | - :envvar:`SAGE_FAT_BINARY` - to prepare a binary distribution that |
| 531 | will run on the widest range of target machines, set this variable |
| 532 | to "yes" before building Sage:: |
| 533 | |
| 534 | export SAGE_FAT_BINARY="yes" |
| 535 | make |
| 536 | ./sage -bdist x.y.z-fat |
| 537 | |
| 538 | Variables to set if you're trying to build Sage with an unusual setup, |
| 539 | e.g., an unsupported machine or an unusual compiler: |
| 540 | |
| 541 | - :envvar:`SAGE_PORT` - if you try to build Sage on a platform which |
| 542 | is recognized as being unsupported (e.g., x86 Solaris, AIX, or |
| 543 | HP-UX), or with a compiler which is unsupported (anything except |
| 544 | gcc), you will see a message saying something like :: |
| 545 | |
| 546 | You are attempting to build Sage on IBM's AIX operating system, |
| 547 | which is not a supported platform for Sage yet. Things may or |
| 548 | may not work. If you would like to help port Sage to AIX, |
| 549 | please join the sage-devel discussion list - see |
| 550 | http://groups.google.com/group/sage-devel |
| 551 | The Sage community would also appreciate any patches you submit. |
| 552 | |
| 553 | To get past this message, export the variable SAGE_PORT to |
| 554 | something non-empty. |
| 555 | |
| 556 | If this is the situation, follow the directions: set |
| 557 | :envvar:`SAGE_PORT` to something non-empty (and expect to run into |
| 558 | problems). |
| 559 | |
| 560 | - :envvar:`SAGE_USE_OLD_GCC` - the Sage build process requires version |
| 561 | 4.0.1 of gcc. If the most recent version of gcc is 3.4.x and you |
| 562 | want to try building anyway, then set :envvar:`SAGE_USE_OLD_GCC` to |
| 563 | something nonempty. Expect the build to fail in this case: Sage is |
| 564 | only guaranteed to build using gcc 4.0.1 or later, so if you insist |
| 565 | on working with gcc 3.4.x, you will have to modify some source code |
| 566 | to get things to work. |
| 567 | |
| 568 | - :envvar:`CFLAG64` - default value "-m64". If Sage detects that it |
| 569 | should build a 64-bit binary, then it uses this flag when compiling |
| 570 | C code. Modify it if necessary for your system and C compiler. |
| 571 | This should not be necessary on most systems -- this flag will |
| 572 | typically be set automatically, based on the setting of |
| 573 | :envvar:`SAGE64`, for example. |
| 574 | |
| 575 | Environment variables dealing with specific Sage packages: |
| 576 | |
| 577 | - :envvar:`SAGE_ATLAS_LIB` - if you have an installation of ATLAS on |
| 578 | your system and you want Sage to use it instead of building and |
| 579 | installing its own version of ATLAS, set this variable to be the |
| 580 | parent directory of your ATLAS installation: it should have a |
| 581 | subdirectory :file:`lib` containing the files :file:`libatlas.so`, |
| 582 | :file:`liblapack.so`, :file:`libcblas.so`, and |
| 583 | :file:`libf77blas.so`, and it should have a subdirectory |
| 584 | :file:`include/atlas/` containing header files. |
| 585 | |
| 586 | - :envvar:`SAGE_MATPLOTLIB_GUI` - set this to anything nonempty except |
| 587 | "no", and Sage will attempt to build the graphical backend when it |
| 588 | builds the matplotlib package. |
| 589 | |
| 590 | - :envvar:`INCLUDE_MPFR_PATCH` - This is used to add a patch to MPFR |
| 591 | to bypass a bug in the memset function affecting sun4v machines with |
| 592 | versions of Solaris earlier than Solaris 10 update 8 |
| 593 | (10/09). Earlier versions of Solaris 10 can be patched by applying |
| 594 | Sun patch 142542-01. Recognized values are: |
| 595 | |
| 596 | - ``INCLUDE_MPFR_PATCH=0`` - never include the patch - useful if you |
| 597 | know all sun4v machines Sage will be used are running Solaris |
| 598 | 10 update 8 or later, or have been patched with Sun patch |
| 599 | 142542-01. |
| 600 | |
| 601 | - ``INCLUDE_MPFR_PATCH=1`` - always include the patch, so the binary |
| 602 | will work on a sun4v machine, even if created on an older sun4u |
| 603 | machine. |
| 604 | |
| 605 | If this variable is unset, include the patch on sun4v machines only. |
| 606 | |
| 607 | - :envvar:`SAGE_BINARY_BUILD` - used by the pil package. If set to |
| 608 | "yes", then force Sage to use the versions of libjpeg, libtiff and |
| 609 | libpng from :file:`$SAGE_ROOT/local/lib`. Otherwise, allow the use |
| 610 | of the system's versions of these libraries. |
| 611 | |
| 612 | - :envvar:`SAGE_PIL_NOTK` - used by the pil package. If set to "yes", |
| 613 | then disable building TK. If this is not set, then this should be |
| 614 | dealt with automatically: Sage tries to build the pil package with |
| 615 | TK support enabled, but if it runs into problems, it tries building |
| 616 | again with TK disabled. So only use this variable to force TK to be |
| 617 | disabled. (Building the pil package is pretty fast -- less than a |
| 618 | minute on many systems -- so allowing it to build twice is not a |
| 619 | serious issue.) |
| 620 | |
| 621 | Some standard environment variables which you should probably **not** |
| 622 | set: |
| 623 | |
| 624 | - :envvar:`CC` - while some programs allow you to use this to specify |
| 625 | your C compiler, the Sage packages do **not** all recognize this. |
| 626 | In fact, setting this variable for building Sage is likely to cause |
| 627 | the build process to fail. |
| 628 | |
| 629 | - :envvar:`CXX` - similarly, this will set the C++ complier for some |
| 630 | Sage packages, and similarly, using it is likely quite risky. |
| 631 | |
| 632 | - :envvar:`CFLAGS`, :envvar:`CXXFLAGS` - the flags for the C compiler |
| 633 | and the C++ compiler, respectively. The same comments apply to |
| 634 | these: setting them may cause problems, because they are not |
| 635 | universally respected among the Sage packages. |
| 636 | |
| 637 | Sage uses the following environment variables when it runs: |
| 638 | |
| 639 | - :envvar:`DOT_SAGE` - this is the directory, to which the user has |
| 640 | read and write access, where Sage stores a number of files. The |
| 641 | default location is ``~/.sage/``, but you can change that by setting |
| 642 | this variable. |
| 643 | |
| 644 | - :envvar:`SAGE_STARTUP_FILE` - a file including commands to be |
| 645 | executed every time Sage starts. The default value is |
| 646 | ``$DOT_SAGE/init.sage``. |
| 647 | |
| 648 | - :envvar:`SAGE_SERVER` - if you want to install a Sage package using |
| 649 | ``sage -i PKG_NAME``, Sage downloads the file from the web, using |
| 650 | the address ``http://www.sagemath.org/`` by default, or the address |
| 651 | given by :envvar:`SAGE_SERVER` if it is set. If you wish to set up |
| 652 | your own server, then note that Sage will search the directories |
| 653 | ``SAGE_SERVER/packages/standard/``, |
| 654 | ``SAGE_SERVER/packages/optional/``, |
| 655 | ``SAGE_SERVER/packages/experimental/``, and |
| 656 | ``SAGE_SERVER/packages/archive/`` for packages. See the script |
| 657 | :file:`$SAGE_ROOT/local/bin/sage-download_package` for the |
| 658 | implementation. |
| 659 | |
| 660 | - :envvar:`SAGE_PATH` - a colon-separated list of directories which |
| 661 | Sage searches when trying to locate Python libraries. |
| 662 | |
| 663 | - :envvar:`SAGE_BROWSER` - on most platforms, Sage will detect the |
| 664 | command to run a web browser, but if this doesn't seem to work on |
| 665 | your machine, set this variable to the appropriate command. |
| 666 | |
| 667 | - :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET` - set this to something |
| 668 | nonempty to force Sage to set the :envvar:`LD_LIBRARY_PATH` before |
| 669 | executing system commands. |
| 670 | |
| 671 | - :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used |
| 672 | on Mac OS X to set the :envvar:`DYLD_LIBRARY_PATH`. |
| 673 | |
| 674 | - :envvar:`SAGE_CBLAS` - used in the file |
| 675 | :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`. Set this to the |
| 676 | base name of the BLAS library file on your system if you want to |
| 677 | override the default setting. That is, if the relevant file is |
| 678 | called :file:`libcblas_new.so` or :file:`libcblas_new.dylib`, then |
| 679 | set this to "cblas_new". |
| 680 | |
| 681 | Variables dealing with doctesting: |
| 682 | |
| 683 | - :envvar:`SAGE_TESTDIR` - a temporary directory used during Sage's |
| 684 | doctesting. The default is to use the directory ``$DOT_SAGE/tmp``, |
| 685 | but you can override that by setting this variable. |
| 686 | |
| 687 | - :envvar:`SAGE_TIMEOUT` - used for Sage's doctesting: the number of |
| 688 | seconds to allow a doctest before timing it out. If this isn't set, |
| 689 | the default is 360 seconds (6 minutes). |
| 690 | |
| 691 | - :envvar:`SAGE_TIMEOUT_LONG` - used for Sage's doctesting: the number |
| 692 | of seconds to allow a doctest before timing it out, if tests are run |
| 693 | using ``sage -t --long``. If this isn't set, the default is 1800 |
| 694 | seconds (30 minutes). |
| 695 | |
| 696 | - :envvar:`SAGE_PICKLE_JAR` - if you want to update the the standard |
| 697 | pickle jar, set this to something nonempty and run the doctest |
| 698 | suite. See the documentation for the functions :func:`picklejar` |
| 699 | and :func:`unpickle_all` in |
| 700 | :file:`SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online |
| 701 | `here (picklejar) |
| 702 | <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.picklejar>`_ |
| 703 | and `here (unpickle_all) |
| 704 | <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.unpickle_all>`_. |
| 705 | |
| 706 | .. |
| 707 | THIS INDENTED BLOCK IS A COMMENT. FIX IT ONCE WE UNDERSTAND |
| 708 | THESE VARIABLES. |
| 709 | |
| 710 | Variables dealing with valgrind and friends: |
| 711 | |
| 712 | - :envvar:`SAGE_TIMEOUT_VALGRIND` - used for Sage's doctesting: the |
| 713 | number of seconds to allow a doctest before timing it out, if tests |
| 714 | are run using ``??``. If this isn't set, the default is 1024*1024 |
| 715 | seconds. |
| 716 | |
| 717 | - :envvar:`SAGE_VALGRIND` - ? |
| 718 | |
| 719 | - :envvar:`SAGE_MEMCHECK_FLAGS`, :envvar:`SAGE_MASSIF_FLAGS`, |
| 720 | :envvar:`SAGE_CACHEGRIND_FLAGS`, :envvar:`SAGE_OMEGA_FLAGS` - flags |
| 721 | used when using valgrind and one of the tools "memcheck", "massif", |
| 722 | "cachegrind", or "omega" |
| 723 | |