Macaulay 2 by Daniel R. Grayson and Michael E. Stillman available from http://www.math.uiuc.edu/Macaulay2/ Welcome to Macaulay2! This file tells how to install Macaulay 2 from a binary distribution on unix systems such as linux, or under Microsoft Windows. If you have any difficulty with these instructions, please email us. --------------------------------------- -- Strengthen your operating system --- --------------------------------------- If you are running under Microsoft Windows, you should first make your operating system look as much as possible like a unix operating system. The way to do this is to install cygwin, available from http://cygwin.com/. Be sure to install X11 and emacs. The rest of the instructions should be followed in a cygwin bash command shell. --------------------------------------- -- Download and unpack Macaulay2 ------ --------------------------------------- In your browser, visit the web page at http://www.math.uiuc.edu/Macaulay2/Downloads/ and download the appropriate pair of files for your architecture and operating system. (Actually, if you are reading this file, you have already done this step.) Details about the file naming conventions are visible there. Typical names include these: Macaulay2-1.2-common.tar.gz Macaulay2-1.2-i486-Linux-Generic.tar.gz If there is a later version than 1.2, use that instead. The files with "common" in the name contain the Macaulay 2 files that are independent of the architecture of your computer. The files with a string such as "i486-Linux-Generic" in the name contain the architecture-dependent files, including the executable file "M2". The component "i486" is the architecture of the machine, the component "Linux" is the operating system, and the component "Generic" is the issue of the operating system. Possible issues of GNU/Linux include Ubuntu, Debian, Fedora, and Generic; the Generic issue is linked with as few dynamic libraries as possible, and might be appropriate if you aren't able to install additional libraries on your computer, for lack of root access. Unpack the gzipped tar files as usual, in whatever directory is convenient, say in /foo/bar, as follows. cd /foo/bar tar zxfp Macaulay2-1.2-common.tar.gz tar zxfp Macaulay2-1.2-i486-Linux-Generic.tar.gz (If you downloaded files ending with bz2 instead of gz, then change the z in the first parameter to j.) After unpacking the tar files, you will see that a directory tree rooted at /foo/bar/Macaulay2-1.2 has been created. The subdirectories and files are organized in a way that mimics the usual unix tree of subdirectories rooted at /usr. For example, there are subdirectories called bin, info, lib, and share. There are also some extra files called: INSTALL (this file), encapinfo, postinstall, and preremove. ------------------------------------------------- -- Install method for Users --------------------- ------------------------------------------------- Arrange for Macaulay 2 to set up your .emacs files and your command shell init files so that M2 will be on the path. But first see the warning below, if you are not following our procedure precisely. cd /foo/bar/Macaulay2-1.2 cd bin ./M2 -e 'setup();exit 0' You will be give an opportunity to review, accept, or reject the proposed changes to your files. Backups will be made. After you log in again, your PATH will have Macaulay2's bin directory on it. The variables MANPATH, INFOPATH, and LD_LIBRARY_PATH will also have entries added to them. Warning: there is at least one important situation where you will not want to run the Macaulay 2 "setup()" command. For example, suppose you have installed M2, not in its own private location as described above, but in a directory with many other executable files. Suppose also that your account is adapted so it will run programs correctly on hardware of more than one architecture, or on differing operating systems, or even on various releases of the same operating system. Then "setup()" will modify your command shell init files so the directory containing M2 will the first one searched when looking for a program. If you then try to use your account on different hardware, incorrect programs may be found, namely, those in the same directory as M2. Similarly, incorrect sharable libraries may also be found. The most common cause for a failure at this point is for some dynamic libraries not to be found on your system. In this case, under linux, the utility "ldd" may be used to display the libraries required, together with an indication of whether any are not found: $ ldd Macaulay2/bin/M2 linux-gate.so.1 => (0xffffe000) libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x4001e000) libgfortran.so.2 => /usr/lib/libgfortran.so.2 (0x40111000) libgdbm.so.3 => /usr/lib/libgdbm.so.3 (0x401a8000) libmpfr.so.1 => /usr/lib/libmpfr.so.1 (0x401af000) libgmp.so.3 => /usr/lib/libgmp.so.3 (0x401ed000) libreadline.so.5 => /lib/libreadline.so.5 (0x40232000) libhistory.so.5 => /lib/libhistory.so.5 (0x40263000) libncurses.so.5 => /usr/lib/libncurses.so.5 (0x4026b000) libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0x402af000) libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x402d5000) libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0x402e0000) /lib/ld-linux.so.2 (0x40000000) libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0x4042a000) Alternatively, under Cygwin, the utility "cygcheck" may be used to determine which library files are needed, as well as to determine which packages are needed to provide them. ------------------------------------------------- -- Install method for System administrators ----- ------------------------------------------------- The easiest and way to install Macaulay2 is with "epkg", available from http://www.encap.org/epkg/ The files encapinfo, preremove, and postinstall in the top level directory or init files for that program, whose purpose is to put appropriate symbolic links from locations under /usr or /usr/local to the files in /foo/bar/Macaulay2-1.2. If you do this, then Macaulay2's files can be found without modifying any paths. Otherwise, each user will have to run our "setup()" command, as described above, to set the paths correctly. The paths we have in mind are the environment variables "LD_LIBRARY_PATH", "INFOPATH" (used by "emacs" and "info"), and "PATH", as well as the emacs variable "load-path". Moreover, an installation made with "epkg" can be reliably removed. If you manually remove the files without asking "epkg" to remove the symbolic links, the only thing left behind will be symbolic links pointing nowhwere, which take up little space on the disk and can be easily found and removed manually. Another thing "epkg" does is to run the "postinstall" script we provide, which runs "dumpdata" (if implemented on your system) and puts directory entries for Macaulay2 and each of its packages into the master info dir file, making the Macaulay2 documentation visible to the user who uses "info", stand-alone, or in emacs. However, if you don't have "epkg", you can install Macaulay2 directly, as follows. Warning: this direct approach is not as good, because it may wipe out the previous version of Macaulay 2, and because there is no reliable way to remove all the files you've installed. Copy the contents of the subdirectories of /foo/bar/Macaulay2-1.2 into /usr or /usr/local/. If you have gnu "cp", the following command will do it: cd /foo/bar/Macaulay2-1.2 cp -ai bin info lib share /usr/local The "i" option to "cp" will prompt you before clobbering a file in the target directory. The reason not to use the command cp -ai . /usr/local is to avoid copying the extra files, including this one. On some systems Macaulay2 comes with dynamic libraries, in the "lib/Macaulay2/Core/lib" subdirectory, so if you want to change /usr/local to something nonstandard, M2 may not be able to find its dynamic libraries unless you add /foo/bar/Macaulay2-1.2/lib to the search path. Under linux, that would involve editing /etc/ld.so.conf or setting the environment variable LD_LIBRARY_PATH. ------------------------------------------------- -- Dumping data --------------------------------- ------------------------------------------------- Here is an additional step that will speed later loading of the program on linux systems and solaris systems. (Mac OS X is sufficiently different from Unix that we haven't been able to implement dumpdata under it yet.) Issue the following command: M2 --dumpdata It will save a file with a name of the form lib/Macaulay2/Core/cache/Macaulay2-*-data in the directory tree where you have installed it. It contains the result of interpreting the source code written in the Macaulay 2 language. The next time you start M2 it will try to load the file. On some systems such loading is rarely successful. In that case, just delete the saved data file. In any case, loading Macaulay 2 should take less than a second. ------------------------------------------------- -- For Users, after installation ---------------- ------------------------------------------------- On a command line, type 'M2' (without the quotes). If Macaulay2 has been installed properly, then you should see a prompt such as this: % M2 Macaulay 2, version 1.2 with packages: Classic, Core, Elimination, IntegralClosure, LLLBases, Parsing, PrimaryDecomposition, SchurRings, TangentCone i1 : At this point you should try entering some simple Macaulay2 commands, such as these: 100! R = QQ[a..d] (a+b+c+d)^4 C = res coker vars R C.dd Now type viewHelp This starts your default web browser (if it is not already running), and then opens the main Macaulay2 documentation page index.html file mentioned below. We suggest that you bookmark this page. By the way, to get the html help on a topic, such as "ideals", use viewHelp "ideals" To get help on an object, such as a function or type, use a command such as viewHelp res To exit Macaulay2, type one of: exit, end, quit, or the end of file character, which is usually set to CTRL-D. ------------------------------------------------- -- The Macaulay2 application directory ---------- ------------------------------------------------- If this is the first time that you have run Macaulay2 from your account, Macaulay2 creates an "application directory" for Macaulay2 in your home directory. Under unix, that directory is named ".Macaulay2", and under Mac OS X, it is called "Library/Application Support/Macaulay2". The application directory contains several useful files and directories: init.m2 This file is run every time you start Macaulay2 code/ This directory is on your Macaulay2 path, so any .m2 files you put here are easy to load in Macaulay2. index.html This is the top page for the Macaulay2 html documentation. It includes the Macaulay2 html distribution, together with any html files from installed Macaulay2 packages. encap/ A directory containing one subdirectory for each installed package. The subdirectory houses the files for that package. local/ A directory tree containing symbolic links to the files of each installed package. local/info/ A directory with links to the info files for each installed package. You may wish to add this directory to the list of directories in your environment variable INFOPATH. After creating this directory, Macaulay2 never modifies init.m2 or the code directory. The page index.html is rewritten each time M2 is started. Finally, Enjoy! You should now be up and running. From the bookmarked web page, choose 'Macaulay2', and then 'getting started', for a first Macaulay2 session, as well as how to use the Macaulay2 emacs interface. If you have any questions, or problems, please contact one of us, or post a message at our google groups web site: http://groups.google.com/group/macaulay2