NCL > Download > Windows notes

Installing and running NCL under Cygwin/X

This document contains detailed notes on installing and running NCL on a Windows system under Cygwin/X.

You must first download and install the 32-bit version of Cygwin/X. Cygwin/X provides you with a UNIX shell and an X server from which you can then run NCL.

Very important note: You must install the 32-bit version of Cygwin/X and not the 64-bit version of Cygwin/X. To get the 32-bit version of Cygwin/X, install it via the "setup-x86.exe" program and not the "setup-x86_64.exe" program. Details are included below.

Here are some step-by-step instructions for getting NCL to run under Cygwin/X. Please read these instructions all the way through before starting the installation.


Install Cygwin/X

To download and install Cygwin/X, go to the URL:

http://x.cygwin.com/

Read the "Downloading and installing" paragraph, which tells you which installation file you need to download and what to do with it. These notes are based on running version 2.891 of setup-x86.exe or later.

Important note: Cygwin comes with two versions of the setup program. They are called setup-x86.exe and setup-x86_64.exe. Download the setup-x86.exe one, because the other one is for 64-bit Cygwin. NCL can't be installed under 64-bit Cygwin because there are many external packages that NCL depends on that aren't buildable under 64-bit Cygwin.

We recommend that you look through the "Installing Cygwin/X" in the Cygwin/X User's Guide, as it has some nice diagrams showing you each step of the installation process.

We found a nice video on installing Cygwin. This video is for Cygwin and not Cygwin/X, but the instructions are pretty much the same. Make sure you point your browser at x.cygwin.org instead of cygwin.com, and that you download the "setup-x86.exe" program instead of "setup.exe". At the 4:12 mark in the video, it talks about how to select various packages for Cygwin, which will be very helpful when you get to the next section on selecting the required packages you have to download. You don't need to install the packages that the instructor is talking about, but it certainly won't hurt anything if you do.

When you start the installation process (by downloading "setup-x86.exe" and double-clicking on the file wherever you downloaded it), you will be asked where to install Cygwin. I highly recommend that you select the default options, unless you know what you are doing.

You will eventually be asked to select a mirror site from which to download the software. I have found that some mirrors work better than others, and you may have to try several before you get a successful installation. I recommend starting with a mirror that is close to your geographic location, so the download is hopefully quicker.

Once you select a mirror site, you will be prompted for which packages to install. The packages have categories like "Shells", "Devel", "Graphics", etc. Clicking on the plus (+) sign next to each category name will expand or close the list of packages associated with that category. There's a search box at the top that is very useful to find packages that you are not sure what category they're in.

Note that when you select one package, it may cause several other packages to be chosen as well. This is okay; don't go back and unselect those packages!

Some categories and their related packages that you should install are included below:

  • Category "Devel": install "autoconf", "binutils", "bison", "byacc", "flex", "gcc", "gcc4", "gcc4-fortran", "gcc-g++", "gdb", "make", "makedepend", "openssl-devel".

  • Category "Editors": [optional] some popular editors that you might want for editing your files include "nedit", "emacs", and "vim".

  • Category "Graphics": [optional] install "ghostscript" for viewing PostScript files, "ImageMagick" for "convert"

  • Category "Libs": "expat", "libcurl4", "libexpat-devel", "libgfortran4", "libidn-devel", "libxml2", "libtirpc", "zlib"

  • Category "Net": `install "libcurl-devel", "libcurl4", and "openssh".

  • Category "Shells": install "bash", "sh-utils", "pdsh", and "tcsh".

  • Category "X11": install all of the required packages that the "Installing Cygwin/X" section mentions (see #15 where it lists all the "X11" packages and whether they are required or optional). As of July 2018, the list of packages that we recommend are:

    • libX11-devel
    • libX11-6
    • libXaw-devel
    • libXaw7
    • libXm4
    • libXmu-devel
    • libXpm4
    • libXt-devel
    • libcairo-devel
    • libcairo2
    • libfontconfig-devel
    • libfontconfig1
    • libfreetype-devel
    • libfreetype6
    • libxcb-devel
    • xauth
    • xclock
    • xinit
    • xorg-server
    • xterm
    • X-start-menu-icons
    • X-startup-scripts

To select any of these packages for installation, click on the little circular icon next to it until you get a version number. Make sure you select the latest version number, if there are multiple ones. Some of the other options will be things like "skip", "uninstall", and "keep", which you don't want to use the first time through.)

If the installation is successful, then the last item may be a window asking if you want to create some icon shortcuts for your desktop. Answer "yes" to this question as it will provide you with a little "startxwin" icon under Windows that you can double-click to start up Cygwin/X.

If the installation fails or hangs while trying to install the software, then reboot if necessary, and rerun the setup-x86.exe file as you did before, only this time choose a different mirror site.


Run Cygwin/X

Once the installation of Cygwin/X is complete, you need to run Cygwin/X if you plan to run NCL scripts that send their graphics to an X11 window. If you don't care about X11 windows, then you can run NCL commands from a Cygwin window.

To run Cygwin/X, you must first run Cygwin, and type "startxwin" in the Cygwin Terminal. If this is successful, then a little "X" icon will appear on your task bar (usually in the lower right of the screen). If you are having difficulty starting Cygwin/X, then read the section "Using Cygwin/X" on how to start it.

Note for Windows 10 users: The Cygwin/X icon will show up as a small icon with a black C and a green X inside of it. If you left-click on this, a menu will come up. Select "System Tools" and then "XTerm" to start Cygwin/X.

You must run Cygwin or X/Cygwin before proceeding to the next section.

Tip: if you installed Cygwin to the suggested location, then the Cygwin files will be installed under various directories under "c:\cygwin", and a home directory will be created for you under a path like "c:\cygwin\home\".


Make sure you have a Cygwin home directory

Note: some users have reported that a home directory has not been set up for them by Cygwin. I read in several FAQs that if the name of your home directory has a space in it, it won't work. I found an FAQ on this topic at http://www-cdf.fnal.gov/~cplager/cygwin.html#tidbits:

Cygwin doesn't like it if there is a space in your Windows username. If you have a space, do the following after installing Cygwin:

  • Edit /etc/passwd (using either emacs, vi, or even Windows Wordpad)
  • Find your entry (it will start with your windows username)
  • Take the space out of your username (1st entry) and your home directory (2nd to last entry).
  • Quit all Cygwin
  • Use Windows Explorer to rename your home directory (for example "C:\cygwin\home\cplager")


Download NCL

Now you are ready to download and install NCL. If you haven't already, go to the Climate Data Gateway web site and download the NCL binary that has the word "CYGWIN" in the name of the file.

Here's a direct link to the location of NCL V6.5.0 for Cygwin.

A good place to save this file is in the location "c:\cygwin\home\xxx", where xxx is the home directory the Cygwin/X installation set up for you.


Install NCL

Once you have the *.tar.gz file, decide where you want to install NCL. If you are new to UNIX and don't know where you want to put it, then I recommend installing NCL in the directory "/usr/local". I'll use this path in my example below, and I will assume that you saved the file to "c:\cygwin\home\xxx", using "JohnDoe" as an example for xxx, and "ncl_ncarg-6.5.0.CYGWIN_NT-10.0-WOW_i686.tar.gz" as the name of the file. (The name of the file may vary slightly, since the version number changes almost monthly.)

From the Cygwin/X window that you opened earlier, type the following commands:

    mkdir /usr/local
    cd /usr/local
    gunzip /cygwin/home/JohnDoe/ncl_ncarg-6.5.0.CYGWIN_NT-10.0-WOW_i686.tar.gz
    tar -xvf /cygwin/home/JohnDoe/ncl_ncarg-6.5.0.CYGWIN_NT-10.0-WOW_i686.tar
Note: the path "/usr/local" may already exist, in which case you'll get an error message when you type "mkdir /usr/local". This is okay, and you can safely ignore the message.


Set up your environment to run NCL

Every user of NCL needs to set their environment before they can use NCL. You can do this by opening your "c:\cygwin\home\xxx\.bashrc" (or "c:\cygwin\home\xxx\.bash_profile" if ".bashrc" doesn't exist) file with a UNIX editor and adding the lines:

    export NCARG_ROOT=/usr/local
    export PATH=/usr/local/bin:$PATH
Please note that you must use a UNIX editor to change this file, and not a Windows application like "notepad". The UNIX editor should be invoked from a Cygwin or X/Cygwin window. If you are unfamiliar with UNIX editors, we recommend that you use nedit, which is available through the Cygwin "setup-x86.exe" program.

Make sure you add the above lines after the last reference to PATH. If PATH already has "/usr/local/bin" as part of it, then you don't need to add the last line.

If you plan to use csh (C-shell) or tcsh , then add the following lines to your "c:\cygwin\home\xxx\.cshrc" (or ".tcshrc") file:

    setenv NCARG_ROOT /usr/local
    setenv PATH /usr/local/bin:$PATH
To make sure these changes take effect right away, you can "source" the files, or completely exit your Cygwin/X window and start it up again. Here's how to source the files:

csh/tcsh:

    source ~/.cshrc  
    source ~/.tcshrc

bash/ksh:

    . ~/.bashrc
    . ~/.bash_profile


Set up C-shell

If you plan to use the "ng4ex" script, then you'll need to make sure you have C-shell before you can run it.

In the same Cygwin/X window, type:

   which csh
   which tcsh
If it reports that csh cannot be found but that tcsh can, then type the following:
    ln -s /usr/bin/tcsh.exe /usr/bin/csh.exe
    csh
This will put you into a C-shell environment. You only need to execute the "ln -s" command once, but the "csh" command you will need to execute any time you are not in C-shell.

If the above "which" commands report that neither "tcsh" or "csh" can be found, thn you need to run "setup-x86.exe" again, and make sure that you select the "tcsh" package (which falls under the "Shells" category) to be installed.


Set up DISPLAY environment variable

In order to run any X applications, including running NCL to display graphics to your screen, you may need to set up your environment by opening "c:\cygwin\home\xxx\.bashrc" in your favorite editor, and adding the following lines at the bottom:
    export DISPLAY=:0.0
If you are using C-shell, then edit "c:\cygwin\home\xxx\.cshrc" and add the following line:
    setenv DISPLAY :0.0
You should now be ready to run NCL.


Test NCL

To test your installation of NCL, type the following:

    ncl -V
This should echo the version of NCL, like "6.5.0".

For a graphical test, type:

    cp $NCARG_ROOT/lib/ncarg/nclex/xyplot/xy04n.ncl .
    ncl xy04n.ncl

A window with an XY plot should pop up. If you click anywhere in the window with your left mouse button, the window will go away.

If you have problems, then please review the troubleshooting section that follows.


Troubleshooting problems

If you are having problems running the test in the above section, then here are some troubleshooting tips:

  • If you get an error about "ncl" not being able to find a missing "libxxxx.so" library, then rerun the Cygwin "setup-x86.exe" program and search for xxxx. Make sure this package will get installed and finish running the "setup-x86.exe" program. You will probably need to logout and possibly even reboot for the change to work properly.

  • If you get the error:

     warning:GKS:GOPWK: --X driver error: error opening display
    
    then this probably means that your DISPLAY environment variable is not set, or it is set incorrectly. Please type:
    printenv DISPLAY
    
    and make sure that it is set to what is discussed in the "Set up DISPLAY environment variable" section above.

  • If it appears your DISPLAY is set correctly, and yet "ng4ex" still doesn't work, then you might be running the commands from a Cygwin window, and not a Cygwin/X window. The distinction is important, and you need to be running "ng4ex" from a Cygwin/X Window. Please read the section "Run Cygwin/X" and make sure you follow these instructions and then run "ng4ex" from this window.

    You can tell if your Cygwin window is really a Cygwin/X window by the "X" icon that should appear in the upper left corner of the window.

If you still have problems, then send email to ncl-install@ucar.edu. You need to be a member in order to post.