Q: Quick installation
A: Here are the steps to get a fully working UNIX-like
system on your windows in 15-30 minutes. I assume that
have some knowledge of working in a UNIX-like environment
and have a faster-than-modem internet connection.
1. Go to the cygwin download site (google will find
it for you instantly), and download
the "setup" program. STORE the "setup" program in a permanent
directory (e.g., /c/dload/software) because you will be
using it many more times in the future.
2. "Setup" will ask you to choose some options. I suggest
that you accept the defaults: "INSTALL FROM INTERNET" and
"DIRECT CONNECTION".
3. It will then ask ask you for a location to
store the "setup" files. CHOOSE the same permanent location.
E.g., /c/dload/software/cygwin_files.
This is because "setup" will remember all the software that
that you have installed, and this will be use by "setup"
in the future for automatic updates, reinstallation, etc.
4. Now "setup" will show you all the software that you can
choose from -- you can view this list in various ways
(under "categories", "full", "not installed", etc). You may
poke around briefly, to see what is in store for your --
which is a LOT. You should NOT try to download all at
once (it would take too long). But come back anytime
to get more software as needed.
REMEMBER that "setup" can also "upgrade", "re-install"
or "un-install".
5. I am going to suggest a 2-stage installation:
the first time, you simply accept all the defaults for
downloading. This will quickly install a "base system".
In particular, the default option only downloads the binaries.
Immediately after you have installed the base system,
you run "setup" once more, but this time, you now handpick
the essential software you need for your work.
Personal favorites:
gcc/g++, gmp, gvim, sftp, ssh, make, xwindows, cvs, ...
6. THAT IS ALL!
Use "setup" as often as you like, to search for things
you need, to get the latest version, etc. Here are more
TIPS for second time around.
Q: OK, but I don't know the first thing about unix
A: Yes, cygwin is a variant of unix, so you do know how
to do basic tasks with Cygwin. Here is a simple 20 minute
introduction from nyu:
www.nyu.edu/webguide/development/tutorials/unixcommands.html.
I will mention several global things here: details are found
elsewhere (or do a "google search" on any of the terms mentioned):
(1) Environment
Your environment is controlled by the values of various
variables. For instance, the PATH variable tells the unix
shell where to look for the commands whenever you execute a
command. Another variable is called HOME, which is the path
to your home directory (whenever you invoke the shell this is
your default directory). Another is SHELL.
Typically, the system variables are all caps, but your
own user-defined ones should not be. You can freely set values of
these variables. To see the current value of a variable,
say PATH, you can type
> printenv PATH
.:/home/yap/bin:/cygdrive/c/miktex/bin:/usr/local/bin:/bin
The value of PATH is a sequence of paths, separated by ":"s. I like
to put the first path name to be "." (which means the current
directory). So this is the first plance where my shell looks for
command which I want to execute. If it fails to find it,
it will try the next directory and so on.
To define a variable, we use assign to it:
> myVar=10
> that="1234"
> this=""
Note there is no space before or after the "=" sign.
To use the variable (i.e., to get it's value), just prefix the
variable name with a dollar sign:
> usr=yap
> cd /home/$usr
to cd to /home/yap.
(2) Initialization Files
Your environment is usually set up by various files, some
of them are system-wide (all users of your cygwin installation)
and some private to you (in your HOME directory). E.g., the
private files in your HOME directory are called .bashrc.
You can freely edit these files to customize your environment.
E.g., you can set up your own PATH in .bashrc.
Another useful thing to do is to "alias" the commands you commonly
use into something short and memorable for yourself.
E.g., I like to alias my "list file" command which is normally
called "ls" to the following two versions:
> alias ls='ls -sF -color=tty'
> alias la='ls -a'
(3) Tools
Unix gives you a collection of "tools", and you should get
to know a few. The first tool you need to know about
is the "shell" which controls your interaction with unix.
There are many shell variants,
but as noted in another FAQ, I suggest using the default
shell which is called "bash".
You can easily write "shell scripts" to accomplish common
tasks -- put them in a file, and just execute them!
Another VERY useful tool is "make" file. It can be used
to document tasks in each directory you work on. More later.
Q: How do I access the C: disk from cygwin? Or, for that
matter, any other disks that I can see from Windows?
A: From cygwin, you can get to the C: disk as /cygdrive/c/.
For example, if you want to see the directories and
files in the C: drive, do:
> ls /cygdrive/c
To get to the "Program Files" directory in the C: drive, do:
> cd /cygdrive/c/"Program Files"
If you have a Z: drive as well, then you refer to it
as /cygdrive/z.
I like this permanent solution: create a directory for each
of your disks and mount them:
> cd /
> mkdir c
> mount c: /c
> mkdir d
> mount d: /d
> ...etc
Now you can directly go to the c: drive, for example:
> cd /c
But WE DO NOT RECOMMEND creating and mounting "/a" above
since "ls /" will typically fail as "a:" and generate an ugly
sound when there is no floppy in "a:".
Q: How can I run gvim under cygwin?
A: First set your environment variable DISPLAY:
> setenv DISPLAY localhost:0
> gvim myfile
Q: I am missing standard unix-like utility under cygwin. You may find
standard programs such as "more", "make" or some editors
("vim" or "emacs") missing.
A: When you installed cygwin originally, you probably just
accepted its default settings. This only install certain
basic tools, and perhaps these basic tools did not include
what you regard as "basic".
We suggest you re-run the setup program,
and look for what you are missing.
(See the FAQ for "setup").
Q: Setup program seems straightforward enough, but any other tips?
A: More Setup Tips:
1. When you call up "setup" after the initial setup,
there is a "global choice" for download:
the options are (keep, prev, curr, exp), and it determines
the default action for each piece of software:
(KEEP) Keep the current version
(PREV) Install the previous (presumably more stable) version
(CURR) Upgrade to the latest version
(EXP) Try the experimental version
The default is to "CURR", but my
experience had not been good with this default in the past.
The reason is that I customized some of the configuration files
(e.g., /cygwin.bat) but CURR would overwrite them. They
seem to have avoided this now. But if you have trouble,
I suggest you choose the "KEEP" global option whenever you
run "setup".
Also, if you installed LOTS of software, then the "CURR" option
might take a long time to update all of them.
In addition, it may have un-intended consequences such as
undoing some special steps you may have taken in your installation.
E.g., I usually use link my "latex" program to
"miktex", which is independently installed under windows.
Setup may undo such actions and cause your "latex" to fail.
For more information, see
setup guide.
Q: Which shell should I use?
A: You may be more familiar with other shells, but the default
shell in Cygwin is BASH. We recommend sticking to BASH.
But if you want suggestions for TCSH, see next item.
The relevant files are found under /cygwin.bat and
/etc/bash.bashrc and /etc/profile.
There are more files under /etc. You should set up
your personal version of .bashrc under your own directory.
Q: How do I use another shell other than BASH?
A: Here is an example where we set up TCSH.
There should be similar steps for other shells.
There are 3 steps.
STEP 1: create a text file called /cygwin-tcsh.bat,
containing the following lines:
--------------------------------------------------
@echo off
@echo file: cygwin-tcsh.bat
C:
chdir \cygwin\bin
set HOME=\cygwin\home\yap
tcsh -l
--------------------------------------------------
Note: replace "yap" by the name of your own home directory.
STEP 2: Create a "cygwin" icon on your desktop or your
start program menu. The easiest is to make a copy of
the default "cygwin" icon that is on your desktop and
which calls "bash". Under properties of this icon, set the
target to "C:\cygwin\cygwin-tcsh.bat".
STEP 3: Create a file named /etc/csh.login for csh.
My csh.login file contains these lines:
----------------------------------------------------
echo Running csh.login
# For tcsh under cygwin.
setenv PATH "/usr/local/bin/:/usr/bin/:/bin/:$PATH"
setenv MAKE_MODE unix
unset DOSDRIVE
unset DOSDIR
unset TMPDIR
unset TMP
setenv HOST `hostname`
setenv USER `id -un`
alias ls "ls --color -sF"
alias pu "pushd "
alias po "popd "
alias rrm "rm -f"
set prompt = "$USER@$HOST% "
cd "$HOME"
----------------------------------------------------
Q: How about a sample shell script?
A: First, a "shell script" is just any text file that
contains a sequence of shell commands (one per line).
The first line of a shell script is special, and it
has the form
#!...
where ... can be empty or the path of a shell interpreter.
Typically, your system has a directory /bin or /usr/bin
containing various shell interpreters
(sh, bash, csh, tcsh, ksh, etc).
In general, a line that begins with a "#" (other
the above special case), it means the rest of the line
is to be treated as comment.
If a command line is very long, you can break it up by
using the continuation character "\" (see example below)
Here is a self-documenting sample script:
#!/usr/bin/bash
##################################################
# Sample Shell Script
# To execute this file, put it in a file named "foo.sh"
# Make foo.sh executable (e.g., "chmod a+x foo.sh")
# Now execute this file by invoking "foo.sh".
# Result? You will see three identical files named
# myfile, myhello, myworld.
# What are their contents?
##################################################
##################################################
# variables
##################################################
p="hello world"
##################################################
# simple action
################################################
echo "Hello World!" > myfile
##################################################
# simple looping:
##################################################
for x in ${list}; do \
cat myfile > my${x}
done
##################################################
# end
##################################################
Q: How do I set up my environment? Variables PATH, HOME, etc
A: Your environment is simply the values of various
variables (called environmental variables). Two important
ones are PATH and HOME. To see the current value of a particular
variable, use "printenv ".
The value of HOME is typically your user directory. E.g.,
> printenv HOME
/home/yap
The value of PATH is a list of ":"-separated paths,
and they determine the directories where Cygwin looks
for commands or programs to execute.
E.g., you can set PATH in BASH Shell as follows:
> export PATH=.:/home/yap/bin:/bin:/usr/local/bin
In TCSH Shell, you would do:
> setenv PATH=.:/home/yap/bin:/bin:/usr/local/bin
This says to look first in the current directory ".", then /home/yap/bin,
then /bin, and finally /usr/local/bin.
Better still, since you do not know what the previous value
of PATH is, it is best to simply append what you want to
the front or back of the current value of PATH. E.g.,
I usually like the initial directories to be "." and my own
bin, I do this in BASH:
> export PATH=.:/home/yap/bin:`printenv PATH`
These variables are normally set up by executing various
shell scripts. In cygwin, the following script files
will be executed (in this order, if they are found):
-- /cygwin.bat
-- /etc/profile.
-- $(HOME)/.profile
-- $(HOME)/.bashrc
See this FAQs for information about
cygwin.bat file.
and
.bashrc file.
Cygwin also has some system defaults
such as bash.bashrc found under /etc. The organization of these
files and their location seems to be somewhat in flux,
but search around /etc.
Q: How to customize the Cygwin.bat file
A: When you invoke "cygwin" from Windows, you will
get a new command window. The first file that it
executes is stored in a bat-file
called c:/cygwin/cygwin.bat.
Here is what my cygwin.bat file typically looks like:
@rem file: /cygwin.bat
@rem ===============================
C:
chdir C:/cygwin/bin
set HOME=\cygwin\home\yap
set _YAP_CYGWIN=true
bash --login -i
@rem ===============================
Note that "@rem" marks a comment line.
The first command "C:" just changes our
disk to the C: disk. Next "chdir" changes to the
directory "C:/cygwin/bin" where the executable files for
cygwin are found. (E.g., bash.exe is found here,
and we will execute it shortly.)
Then we set the variable HOME to some directory ---
whenever you start up cygwin, your current directory
will be initialized to the value of HOME.
If cygwin did not automatically set up the
directory for you, you may have to manually create such a directory.
Finally, it calls the bash (as a login shell).
Here is HOME in this case? We assume that
your cygwin is installed in the default directory
of "C:/cygwin". In that case, "/home/yap" is really
"C:/cygwin/home/yap".
You can do other customizations. E.g., I like
to set the variable _YAP_CYGWIN to be true, and
this can be used in other shell programs to
distinguish between cygwin from non-cygwin environments.
Q: How to customize your .bashrc or .bash_profile file
A: This is the main customization file for bash shell.
Of course, if you use some other shell (e.g., tcsh or csh)
then your customization file would be .tcshrc or .cshrc.
Actually, all shells (e.g., bash, tcsh, etc) first checks for the
file .profile before looking for .bashrc or .bashrc_profile.
These files must be placed in your $(HOME) directory
(e.g., /home/yap/.bashrc).
In these customization files, you can put commands such as:
* aliases: e.g., to set default arguments
I might want to alias "ls" to mean "ls -sF".
* setting of environment variables
e.g., export PATH=.:`printenv PATH`
* platform customizations:
e.g., if in unix environment, set
EXEC to the empty string,
but in cygwin environment, set
EXEC to ".exe".
HERE is a stripped down sample of my .bashrc file:
##################################################
# .bashrc file
##################################################
# PATH
#=================================================
# Add "." and "~/bin" to PATH varible:
export PATH=.:/home/yap/bin:`printenv PATH`
# Aliases
#=================================================
alias ls='ls -CF --color=auto'
alias ll='ls -l'
alias pu='pushd'
alias po='popd'
# Cygwin vs. non-cygwin
#=================================================
if [ $_YAP_CYGWIN ]
then
export myOS=cygwin
export VIM="c:\Program Files\Vim\vim63"
else
export myOS=unix
export VIM=/usr/share/vim/vim70
fi
# Shell Prompt customization (cygwin or unix version)
#=================================================
if [ $_YAP_CYGWIN ]
then
export PS1='\[\033]0;cyg:\w\007\033[47;34m\]\u@\[\033[42;30m\W\033[0m\][\!] '
else
export PS1='\[\033]0;unix:\w\007\033[47;34m\]\u@\[\033[43;31m\W\033[0m\][\!] '
fi
##################################################
# END .bashrc
##################################################
If you have errors with the above .bashrc file,
read about a possible cause below.
ADDITIONAL NOTES:
If you want to load the settings, aliases
or definitions in some file "foo", you can always type
"source foo" (or put this line into .bashrc). There
are some differences between .profile and .bashrc.
The former is executed by "login shells" only, but the
latter is executed by all shells.
Q: Mysterious errors in shell scripts, .bashrc, etc
A: You may get mysterious messages when bash reads
your .bashrc or .bash_profile, such as
"\r command not found"
(or similar). When you get rid of empty lines, the
complaints about "\r" disappears, but probably other
errors remain. What is going on?
The answer may lie in the fact that a text file (also
called ASCII file) can come in two formats:
in DOS format or in UNIX format.
Most editors can automatically detect the formats
and work properly in either format.
In the DOS format, a new line is represented by two characters:
CR (carriage return or ASCII code 13) and LF (line feed or ASCII code 15).
In the UNIX format, a new line is represented by only
one character, LF. When your .bashrc file is read,
bash thinks the extra character is the name of a command,
hence the error message.
In Cygwin or unix, you can convert a file INFILE in DOS format
to a file OUTFILE in Unix format by calling:
> tr -d '\15' < INFILE > OUTFILE
NOTE:
If you now compare the number of characters in INFILE and OUTFILE,
you will see that the latter has lost the correct
number of characters (i.e., the number of lines in INFILE):
> wc INFILE OUTFILE
Q: How can I use the X server under cygwin?
A: Note that you already have XFree86, the free version
of X server, when you first installed cygwin. If not,
run the cygwin Setup program again and install it. So you only
have to configure it.
You first make sure that the directory
/usr/X11R6/bin
is in your search path. Under bash, this
was automatically setup, but you have to do it
yourself under tcsh: e.g.
> setenv PATH `printenv PATH`:/usr/X11R6/bin
> rehash
Next, make sure that the .xsession file (or equivalent)
is set up in your home directory.
Finally, from the cygwin prompt, simply call "Xwin", or
to get to spunky.nyu.edu, do:
> Xwin :0 -query spunky.nyu.edu
You can also call:
> xinit
More Options: Wenguang Wang (wang@cs.usask.ca) at U Saskatchewan
(http://www.cs.usask.ca/grads/wew036/latex/xfig.html) suggests
the following: put a .xinitrc file into your home directory,
say, with the following lines:
xhost + localhost
cd
xterm -display $DISPLAY -name "xterm-1" -sb \
-sl 1000 -geometry +0+0 &
xterm -display $DISPLAY -name "xterm-2" -sb \
-sl 1000 -geometry +270+190 &
fvwm2
Here fvwm2 is a window manager, so place a suitable .fvwm2rc
file in your home directory. Go to the official fvwm website
to get more information.
Q: Can I execute programs installed under the Window's directory?
E.g., javac.
A: There is no difference between executable programs
under cygwin and those "native" to Windows. For instance,
if you have installed the java compiler "javac" in the
standard location (say C:/"Program Files"/jdk1.4.1/bin) then
you can directly invoke it. Better still, just link to it:
> cd /usr/local/bin
> ln -s /cygdrive/c/"Program Files"/jdk1.4.1/bin/javac.exe .
> rehash
> javac myProg.java
If you need to access CLASSPATH, you can set this in the Control
Panel, under Systems. Alternatively, you can give it as
an argument to javac. E.g., you have a jar file in your cygwin
directory "/java/lib/pg73jdbc.jar", you can access it thus:
> javac -classpath C:/cygwin/java/lib/pg73jdbc.jar myProg.java
Note that the path here begins from C:, and assumes
your cygwin is found under C:/cygwin.
REMARK: other software that I like to link to are acrobat reader
(for viewing pdf files), miktex (for tex/latex processor),
gsview (for viewing postscript files),
gvim (editor).
Q: After I installed cygwin, and I started it
it gives the following messages:
bash.exe: warning: could not find /tmp, please create!
bash: /etc/profile: Invalid argument
bash: /.bash_profile: Invalid argument
A: You need to first create the directory /tmp. Assuming
your cygwin root directory is called C:/cygwin, that means
you should first create the directory C:/cygwin/tmp.
Q: Why is C:\cygwin\usr\bin invisible from windows?
A: Because it does not really exist. In cygwin,
/usr/bin is just a link to /bin. E.g., if you "ls"
the files in /usr/bin and in /bin, you will see identical
files.
Q: Cygwin with KDE?
A: try this site
KDE on Cygwin/XFree.
Q: Is itoa() missing in Cygwin?
My GCC compiler in Cygwin, could compile the "itoa()" function,
but could not load because "itoa()" is not found in the library!
E.g.,
% gcc test.c -c -- this works!
% ld a.exe -lc -- this fails to find itoa()
A:
Function "itoa()" is normally found in ,
or in CGYWIN. But the libraries (libc.a, etc)
do not seem to have it. Your workaround is to directly
define this function yourself:
/* missing definitions for cygwin:
itoa
and this .def file:
LIBRARY COMCTL32.DLL
EXPORTS
ImageList_Duplicate@4
ImageList_DrawIndirect@4
ImageList_Copy@20
*/
#ifdef __CYGWIN__
char* itoa (int value, char * buffer, int radix);
/* This is no strict ANSI definition, and not in newlib */
#include
char* itoa (int value, char * buffer, int radix) {
if (sprintf(buffer, "%d", value)) return buffer;
else return NULL;
}
#endif
Q: Why can't I type "a.exe"?
Joe writes:
In cygwin, typing "a.exe" has never worked for me, so I've always typed
"run a.exe" and the program worked.
Have you ever heard of this happening and if so, do you know how to fix
it so that the program will run no matter which one you type?
A:
"." is the unix name of the current directory. So, "./a.exe" refers
to the a.exe file in the CURRENT directory.
The reason a.exe does not work for you, but ./a.exe works, is that
your environmental variable PATH did not have "." among
its list of directories (also called "paths") in the PATH
environmental variable.
See our FAQs about "environmental variables".
When you issue a command, the shell searches these directories
for the program to execute. E.g., when your type "ls",
bash will search these paths looking for the program
called "ls" or "ls.exe". Usually, "ls" is found in /usr/bin.
Check this in your /usr/bin to see if this is there.
You can see what are in your search paths by typing:
% printenv PATH
You should see a ":" separated list of directories. E.g., I have
% printenv PATH
.:/home/yap/bin:/usr/local/bin:/usr/bin/:....
(omitted the long list in my PATH)
Notice that I have "." at the front of my search path
(some people do not recommend this, but I have not
found this to be an issue).
Here is how to add "." to your search path:
% export PATH=".:"`printenv PATH`
Now try to see your new value of PATH.
In fact, you should put this export command
to your .bashrc file (in your home directory).
Feel free to
send me your suggestions for this page!