*************************************************************************** Installation guidelines *************************************************************************** Table of contents: I - ABOUT II - DOWNLOAD 1) Retrieving sources from GILDAS homepage 2) Retrieving sources from GIT repository 3) Retrieving binaries from GILDAS homepage 4) Retrieving documentation from GILDAS homepage III - REQUIREMENTS 1) Material 2) Needed tools to build executables 3) Needed tools to build the documentation IV - INSTALL UNDER MAC OSX 1) MacPorts package 2) Installation from sources 3) Troubleshooting V - INSTALL UNDER LINUX 1) Dependencies 2) Compile and install (binaries) 3) Post-installation (binaries) 4) Compile and/or install (documentation) 5) Troubleshooting VI - INSTALL UNDER MS WINDOWS 1) MicroSoft Installer (binary distribution) 2) Installation from sources under Cygwin VII - UNINSTALL 1) Under Linux 2) Under MacPorts *************************************************************************** I - ABOUT ---------- Please contact gildasiram.fr for any question, remark, suggestion. *************************************************************************** II - DOWNLOAD -------------- 1) Retrieving sources from GILDAS homepage: Linux/OSX version of GILDAS are distributed only as sources because binaries are not portable (due to the many different possible combinations of processors, operating system and compilers). Tarballs of the GILDAS sources are distributed at the address: https://www.iram.fr/~gildas/dist/ You have to pick a tarball named gildas-src-mmmyyv.tar.xz. Some hints: - VERSION: the basic rule to pick up a release is to download and install the latest monthly release available on this area. Daily releases are there just as a convenience for beta testers. We strongly discourage standard user to get them. - LABELLING: the suffix 'a', 'b', 'c' and so on indicates that an important bug fix or feature has been added during the month and this could not wait for the new release at the beginning of next month. Such new releases include only these modifications, and not all the on-going developpements. Check the NEWS section for details on the augmented release. - STABILITY: Developpers usually stabilize (if needed) Gildas before each release. Nevertheless, some developments take time and in such a case monthly releases may be skipped. From time to time some releases are suffixed "beta": this indicates that important developments were done and this version is a candidate for a stable release. It is "stable as far as we know", but not tested enough. - REFERENCE VERSION: Finally, the jun22 release (June 2022) is a particular version used at the telescopes. If a newer version is available, standard users should not install the jun22 one, unless they have been told to. There are bug fixes, improvements, and features which have been added in the latest releases, but which won't be in the jun22 release because they do not affect the operations at the telescopes. 2) Retrieving sources from GIT repository: Get the last monthly version from the public GIT repository shell-prompt> git clone \ -b ryy-mmm https://git.iram.fr/gildas/gildas.git gildas-src-mmmyy This command creates the sources of GILDAS in a new gildas-src-mmmyy directory. The "-b ryy-mmm" switch enable you to choose the monthly release you need. Be careful, you here need only the 3 first letters of the current month and the last two digits of the current year. No letter is required: you will automatically end up with the last bug fix of this monthly release. In practice, if you want to fetch the December 2022 sources, just type: shell-prompt> git clone \ -b r22-dec https://git.iram.fr/gildas/gildas.git gildas-src-dec22 It also possible to update this clone at any moment: shell-prompt> cd gildas-src-dec22 shell-prompt> git pull # Fetch the last commits in the current branch If new monthly versions have been released, you should be able to check them out after git pull, e.g. shell-prompt> git checkout r23-jan # Fetch January 2023 release Do not forget to completely clean and rebuild GILDAS after an update (make distclean && make). 3) Retrieving binaries from GILDAS homepage: A self-extracting MS Windows binary distribution (including documentation) of the whole GILDAS package is available at https://www.iram.fr/~gildas/dist/ . Please follow the dedicated installation guide hereafter. 4) Retrieving documentation from GILDAS homepage: Compiled documentation is distributed as tarballs at the address: https://www.iram.fr/~gildas/dist/ You have to pick a tarball named gildas-doc-mmmyy.tar.xz *************************************************************************** III - REQUIREMENTS ------------------- 1) Material: - Building the GILDAS binaries under Linux or Mac OSX requires about 300 MB of temporary disk space (compilation) and 100 MB of permanent disk space (installation). - The gfortran compiler might require up to 5-6 GB of RAM when compiling GILDAS sources. At run time, GILDAS executables require about 1 MB at startup, but then consume as much memory as data created or loaded in memory. 2) Needed tools to build executables: Successful building of GILDAS binaries on a UNIX/Linux/OSX system minimally requires: - Bourne compatible shell (sh, ksh, bash, etc...) for build purpose only. The end-users can then use the GILDAS programs from csh-like or Bourne-like shells. - NROFF for on-line help building. - Perl for automatic interface extraction during compilation process. - A C compiler (either GCC or the native C compiler). - GNU make: The current building system is using the GNU make facility which has some some desirable but non-portable features (i.e. including makefiles, conditions). This does not seem a strong limitation as it is easy to install GNU make for your system. In fact, GNU make is the default for linux boxes. For others OS, just try to type gmake instead of make: it is probably already installed. - A FORTRAN 90/95/2003/2008 compiler: Latest GNU Fortran (gfortran >= 9.0) and Intel Fortran Compiler (ifort > 11.1) are supported. - GTK 2 development tools for graphic and widget support. - Python >= 2.6 and its array module Numpy if you plan to use the Gildas-Python binding, including the Weeds package in CLASS. Python 3 is supported; Gildas will use the Python version as found from the "python" executable in the environment. - CFITSIO if you plan to use MRTCAL. 3) Needed tools to build the documentation: Successful building of PDF/HTML documentation minimally requires recent versions of: - ps2epsi - epstopdf - latex (version 2e with makeidx, graphicx and html package) - latex2html - pdflatex For your convenience, we distribute compiled PDF/HTML documentation in case you do not have those tools. See the distribution section of the GILDAS web page: https://www.iram.fr/~gildas/dist/ *************************************************************************** IV - INSTALL UNDER MAC OSX --------------------------- Gildas and its dependencies can be installed with the MacPorts package manager (www.macports.org). 0) Prerequisites: Both installation methods 1 and 2 below require the installation of: - Xcode, needed by MacPorts. Get it from https://developer.apple.com/xcode/ with an Apple identifier (more than 1 GB to be downloaded from the app store). See e.g. the Xcode installation guidelines suited for MacPorts at www.macports.org/install.php - Xquartz, needed for Gildas plots (www.xquartz.org). XQuartz is successfully installed if the command "xclock" is available and opens a clock in a small graphical window. If not, start Xquartz from Applications > Utilities > XQuartz. - MacPorts, a package manager, is needed retrieve and install transparently Gildas and its dependencies. Follow MacPorts installation guidelines at www.macports.org/install.php MacPorts is successfully installed when e.g. the command "port help" is available. 1) MacPorts package: Gildas is available as a standard package in the MacPorts distribution. Unless you are an advanced user (see below: Installation from sources), this is the recommended way to install Gildas under Mac OS. Once MacPorts and XQuartz are installed, Gildas installation is straightforward. Type: sudo port install gildas The parallelization is enabled by default. The Gildas programs are ready to use right after (type e.g. "greg" in a terminal prompt). Usually the package is updated a few days after a source release (every month), so that the latest enhancements or bug fixes in Gildas are quickly available to Mac users. Updating to the newest release is done with the command: sudo port upgrade gildas You might need to update MacPorts itself first: sudo port selfupdate 2) Installation from sources: As an alternate solution, it is possible to compile Gildas by yourself. You have to use MacPorts to install first the Gildas dependencies. - Installing the dependencies: shell> sudo port install gcc13 shell> sudo port select gcc # show available arguments shell> sudo port select gcc mp-gcc13 # Choose the desired one shell> sudo port install gtk2 shell> sudo port install pkgconfig shell> sudo port install groff - CFITSIO is needed only for the 30m calibration software. Have a look at: shell> sudo port variants cfitsio Then install the correct "variant" e.g. shell> sudo port install cfitsio +gcc13 - Finally you can follow the standard Linux steps to compile Gildas from the sources (see below). 3) Troubleshooting: - If you have problem with rsync when running "sudo port selfupdate", you can modify the file /opt/local/etc/macports/sources.conf by replacing the line: rsync://rsync.macports.org/release/ports/ [default] with: #rsync://rsync.macports.org/release/ports/ [default] https://www.macports.org/files/ports.tar.gz [default] and run "sudo port sync" instead of "sudo port selfupdate". shell> sudo port install gcc13 shell> sudo port install gtk2 shell> sudo port select gcc # show available arguments shell> sudo port select gcc mp-gcc13 - Mac OSX 10.7 (Lion) users: if possible, try to avoid to install Python from MacPorts. If installed, you might experience this bug when the Gildas-Python binding is started at runtime. If so, you should configure your system to prefer the Apple-Python rather than the MacPorts-Python: shell> port select python python27-apple However, note that this may break other Python-related applications installed with MacPorts. - If the Gildas installation fails and the log file shows the following error: :info:build FATAL:/opt/local/bin/../libexec/as/x86_64/as: I don't understand 'm' flag! This problem is described here: https://trac.macports.org/ticket/56919 In short, the assembler program ('as') which is used is not the correct one. Type sudo port install cctools +xcode to switch to the correct version. Then you can resume the Gildas installation. - If the Gildas installation fails and the log file shows the following error: :info:build ld: unexpected token: !tapi-tbd-v3 file '/System/Library/Frameworks//CoreFoundation.framework/CoreFoundation.tbd' for architecture x86_64 This problem is described here: http://mac-os-forge.2317878.n4.nabble.com/linker-errors-ld-unexpected-token-tapi-tbd-v3-file-td363061.html#a363073 In short, you should type: sudo port install ld64 +ld64_xcode Then you should retry Gildas installation. You should clean the previous attempt first: sudo port clean gildas Then proceed: sudo port install gildas + any option if needed - If the program won't open any graphical window and shows this warning instead: Gtk-WARNING **: xx:xx:xx.xxx: cannot open display check that XQuartz server is installed and running (see Prerequisites section above). - If you observe this message when opening a Gildas program, please see the same TROUBLESHOOTING section for Linux: Gtk-WARNING **: Locale not supported by C library. Using the fallback 'C' locale. - GREG hardcopies to PDF are ensured through system utilities ps2pdf and epstopdf. They can be installed thanks to the following ports: shell> sudo port install texlive-basic # provides ps2pdf shell> sudo port install texlive-fontutils # provides epstopdf *************************************************************************** V - INSTALL UNDER LINUX ------------------------ 1) Dependencies: In addition to the standard developper tools (make, gcc, nroff, etc), the following dependencies must be installed. Root priviledges are required here. - Fedora 28 (or redhat-like distributions): Required: dnf install gcc-gfortran gcc-c++ gtk2-devel Recommended: dnf install python-devel numpy libpng-devel texlive-epstopdf Optional: dnf install fftw-devel cfitsio-devel Pre-install: export GAG_SEARCH_PATH="/usr/lib" Install: follow installation steps at paragraph 2 - Ubuntu 20.04 (or debian-like distributions): Required: sudo apt install gfortran g++ libgtk2.0-dev Recommended: sudo apt install python-is-python3 python-dev-is-python3 \ python3-dev python3-numpy texlive-font-utils Optional: sudo apt install libfftw3-dev libcfitsio-dev Pre-install: export GAG_SEARCH_PATH="/usr/lib:/usr/lib/x86_64-linux-gnu", Install: follow installation steps at paragraph 2 2) Compile and install (binaries): Building the binaries should just need the following sequence of commands. Gildas itself does not need root priviledges for installation and execution: it can be unzipped anywhere and installed by any user for its own needs. shell-prompt> unxz gildas-src-mmmyya.tar.xz shell-prompt> tar -xf gildas-src-mmmyya.tar or even simpler, let tar uncompress the archive by itself (automatic detection from the file extension): shell-prompt> tar -xf gildas-src-mmmyya.tar.xz shell-prompt> cd gildas-src-mmmyya At this stage, if you are not under a sh-compatible shell, you have to switch to e.g. bash. Then load the compilation environment: shell-prompt> source admin/gildas-env.sh You can optionally add the compiler to be used with the option "-c" (e.g. source admin/gildas-env.sh -c gfortran). You can also enable the parallelization with OpenMP with the following switch: shell-prompt> source admin/gildas-env.sh -o openmp This is useful in particular in Mapping. Read carefully the messages and warnings returned by the command. You can safely ignore CFITSIO warnings if you don't know what they mean. If everything seems correct, then compile and install Gildas: shell-prompt> make shell-prompt> make install Finally, follow the instructions at the end of the make install process. Installation is successful if you can start the programs 'greg' or 'class' from a new terminal. 3) Post-installation (binaries): After the installation is successful, you can optionally remove the sources and compilation directory (gildas-src-mmmyy). This is useful only to save disk space. On the other hand, this means that in case of update (e.g. for GIT-based downloads) you will have to recompile everything again from scratch. 4) Compile and/or install (documentation): - From the tarball archive (easiest): shell-prompt> mv gildas-doc-mmmyya.tar.xz gildas-exe-mmmyya/ shell-prompt> cd gildas-exe-mmmyya/ shell-prompt> tar -xf gildas-doc-mmmyya.tar.xz - Directly from the sources: Compilation of documentation is not done by default when compiling executables because: i) it requires special tools (see requirements) and ii) it takes time. To compile and install the PDF documentation, type: shell-prompt> make doc shell-prompt> make install-doc To compile and install the HTML documentation, please type: shell-prompt> make html shell-prompt> make install-html 5) Troubleshooting: - This message can be displayed when starting a Gildas program: Gtk-WARNING **: Locale not supported by C library. Using the fallback 'C' locale This is not a GILDAS issue. This means that your locale settings (type "locale" in a terminal) indicate one or more locales that are not installed on your system (type "locale -a" in a terminal for the full list). You should fix your environment variables in order to use an installed locale (e.g. export LANG=en_US.utf8, beware this may change your programs behavior regarding language), or install the missing locale(s). - Conflict with Anaconda: when installed from the downloadable installer, Anaconda comes with a lot of development tools and libraries which override the default system ones, but not in a consistent way. This is proved to break software compilation and/or execution (Gildas and others). For example: astro: /home/user/anaconda/lib/libstdc++.so.6: version `GLIBCXX_3.4.21' not found (required by /home/user/ gildas-exe-jan17a/x86_64-ubuntu16.04-gfortran/lib/libatm.so) This happens because Anaconda gives precedence to its own binaries and include files (duplicate but different versions of system ones) in the user's environment. There are several ways out of this issue: a) Install Anaconda from your OS repositories (instead of custom installation in the user account). This way, there should be a correct integration of Anaconda within the OS. b) Keep Anaconda in the user account, but "hide" it during Gildas installation and execution. In other words, you have to ensure that there is no reference to Anaconda installation paths in the environment variables $PATH and $LD_LIBRARY_PATH. You most likely have to edit your ~/.bashrc. Once this is done recompile, install, and try executing Gildas. If it runs fine, a permanent solution could be to use a shell function which loads Anaconda environment only when needed, e.g. function anaconda() { export PATH=... export LD_LIBRARY_PATH=... anaconda } c) The next time you install Anaconda, you should answer "No" to the question: "Do you wish the installer to prepend the Anaconda<2 or 3>install location to PATH...?". Then use a function like the above example to get it working. Reference: https://docs.anaconda.com/anaconda/user-guide/faq/#distribution-faq-linux-path *************************************************************************** VI - INSTALL UNDER MS WINDOWS ------------------------------ 1) MicroSoft Installer (binary distribution) - Disclaimer: GILDAS under Windows is supported on a best effort only. Only 64 bits binaries are delivered. This means 32 bits version of MS Windows are not supported (this includes Windows XP). - Get the Gildas installation package called gildas-win64-mmmyya.exe where "mmmyy" indicate the release date. - Execute the installation package. Choose a destination folder name without white spaces. Under Windows Vista, choose the "just for me" installation option. - Optionaly edit the gag.dico.lcl file to specify your Gildas preferences, if any. It can be found in the "etc" directory in the installation folder. - If the you have no administrator rights, you have set the PATH environment variable after installation. In a terminal, type: setx PATH "%PATH%;C:\gildas\bin" where "C:\gildas" should be replaced by the installation folder if you used another one. 2) Installation from sources under Cygwin - You can compile Gildas from sources using the Cygwin environment (https://cygwin.com). Only the 64 bits version is supported. Among the basic cygwin kernel and tools, you also need to install the following packages: * make, perl, pkg-config, groff * gcc-core, gcc-gfortran, gcc-g++ * libgtk2.0-devel, libpng-devel, xorg-server, xinit * python, python-devel, python-numpy Any missing package can be installed after the Cygwin installation by re-running the installer and choosing the same mirror as before. - Once all dependencies are installed, compiling and installing Gildas is as easy as under Linux (see section V-2). You can check that the Cygwin environment is detected in the following message: "Selecting GILDAS version: mmmyy, source tree, x86_64-cygwin-gfortran" - Before running Gildas programs, make sure the X server is running, either by executing it from the Windows Programs list, or by typing "startxwin" in a Cygwin terminal. - You might also need to add the following line in your ~/.bash_profile: export DISPLAY=:0 *************************************************************************** VII - UNINSTALL --------------- 1) Under Linux - Except if you want to save disk space, you have no need to uninstall any previous Gildas installation. Each version goes into its own 'gildas-src-XXX' and 'gildas-exe-XXX' directories. The default version used is ruled by the environment variable $GAG_ROOT_DIR that is set in user's ~/.bash_profile. You can modify it as you want to point to the desired version. - Remember to start a new terminal each time you modify your ~/.bash_profile . - For a complete uninstall of Gildas, just remove the directories 'gildas-src-XXX' and 'gildas-exe-XXX', and suppress the lines related to Gildas in your ~/.bash_profile 2) Under MacPorts - MacPorts keeps older Gildas versions when you install a new one. At some point you might want to clean all the useless versions. You can check for all installed version with sudo port installed gildas You will see a list of versions with a @ name, e.g. gildas @201808b_0+gcc7 gildas @201808b_0+gcc7+openmp gildas @201809a_0+gcc7+openmp (active) Uninstalling a single version can be done with e.g. sudo port uninstall gildas @201808b_0+gcc7 Uninstalling several versions can be done with sudo port uninstall gildas Answer at the prompt which versions are to be uninstalled. - If you wish to completely uninstall MacPorts and Gildas, check here for the MacPorts recommendations: https://guide.macports.org/chunked/installing.macports.uninstalling.html ***************************************************************************