Detailed FAQ about Installing Cygwin and Using CSIM Under It

Cygwin installation and usage can be somewhat confusing, especially to persons unfamiliar with basic computer skills. While we cannot replace a multi-year college curriculum, the following FAQ addresses some issues that arise, and explains detailed instructions for those who might need it. We are providing this information from actual past experiences to provide further assistance.

We are continually trying to improve the installation experience. If you find any errors in the explanations, -or can suggest improvements-, please forward back to us, so that we may improve the process for future users.

As a reminder, the Cygwin install notes are located at: Cygwin Install.
They should be followed carefully to avoid problems. Having assisted with many Cygwin installs, the number one problem by far has been selecting "Install All" during the installation process. In my first few install attempts, even though I thought I had selected it correctly, but had not. (Note that "All - Default" is not the same as "All - Install". Default provides none of the needed packages. See more below.)

Q1: Besides a compiler, what advantages does Cygwin bring to my PC?

A: Some nice capabilities provided by Cygwin:

Command-aliases - Substitute complex or frequently accessed commands with simple easily remembered names that can be used from anywhere.
Ability to select text, copy, and cut&paste in text-windows or command-windows with mouse.
Repeat commands with exclamation mark (! or bang) - !! repeats the last command, !-n repeats the nth previous command, and !n repeats the nth command.
Command-line completion - Type only the first few letters of a file name, and hit <tab>. If the letters are enough to uniquely identify a single file, it will complete the file-name for you, but only up to the part that is unique. This avoids much typing (and typo's). Intelligent completion. Will stop where file name is ambiguous, instead of selecting random files, like newer MSwin shell does (which is cumbersome + very dangerous).
On-line manuals - Type: man <any-command> ... And it will bring up a manual page describing how to use that command. Includes programming commands, as well.
Command-line editing - Enables use of arrow and delete commands to alter or fix commands.
Command history -
a.) Up arrow to retrieve previous commands,
b.) Type: history ... To see list of previous commands.
c.) Short cuts: Type: !<command-number> or !<first-few-letter(s)> ... to repeat a previous command.
Shows what directory you are in by typing: pwd (Print Working Directory).
Allows you to resize the window to any arbitrary size by merely stretching the window border. Enables windows wider than 80-columns!
Enables using the mouse to select or cut&paste text with single click.
Simplifies cut&paste. Just select text with mouse, and paste by pressing middle-mouse button. (No combined menu or keyboard operations needed.)
Text editors that are more capable than NotePad or Word, let you jump by words, lines, pages, or to specific line numbers, or kill lines quickly without repeatedly moving your hand off the keyboard.
Ability to record, combine, and issue commands from flexible scipt files, minimizes need to learn and remember complex set of window operations or command sequences.
Ability to make symbolic file/directory links, for example to save disk space.
Ability to push directories onto a directory stack, to rapidly jump back&forth between or around multiple directories (pushd or pd).
... And many other work-saving capabilities.
Note that everything is case-sensitive under Cygwin.

Q2: Cygwin installs ok, but when I click the Cygwin icon, the bash shell window opens and then closes right away. What should I do?

A: Try starting Cygwin from a DOS cmd window. It will provide further information. Report to us what it says.
To bring up a DOS cmd window, click Start (lower left of screen), Accessories, Command Prompt. If you cannot find this, an alternate method is to select Start (lower left of screen), Run, and then type cmd. This should bring up a window to type commands and see responses.
A good way to start Cygwin is to type:
c:\cygwin\usr\X11R6\bin\startxwin.bat
assuming that you installed Cygwin on your C: drive under cygwin. If you installed it elsewhere, they modify the above command accordingly.
If this command works, you will soon see a new terminal window. It is the Cygwin window from which you can install and invoke CSIM. If not, you might see some error messages that indicate what the problem is. Report to us what it says so we can help diagnose it.

Q3: Cygwin installs ok, and when I click the Cygwin icon, a terminal window appears. I then installed CSIM, but when I invoke the gui, I get the following error message:
Error: Can't open display:

A: This indicates that Cygwin's X-server is not running. It can be fixed by typing:
startxwin.bat
from within a Cygwin terminal window. You can test whether it started by typing: xterm &
It should pop-up a new terminal window. If that does not work, it indicates a bad or incomplete Cygwin install. You need the X-server to run graphical applications under Cygwin. (See below for more info about correcting installation problems.)

Q4: General category of questions:

From within Cygwin, I do not see where I placed the CSIM files?
When I try to source the CSIM setup file, it says File not found ?
I would like to add the "source csim/setup" line to my .bashrc file but I have not found it?
Where should the .bashrc file located?

A: When you start Cygwin, it places you into a "home" directory. You can see where it is by typing: pwd (Which stands for "print working directory".) It should show something like: /home/yourname.
Usually it is actually located under C:Cygwin\home\yourname, where yourname may be your user-name or possibly "unknown". And where the drive and top-level Cygwin directory are wherever you installed Cygwin. The key point is that under Cygwin, you start out under a home subdirectory. You can move anywhere by changing directories with cd. You can move outside the Cygwin directories by specifying a full absolute path including the drive letter. You can see the files in a directory with the dir -la command.
A pitfall: You will have trouble if your home directory name contains spaces. It must be one word. If so, create a new home directory and use that. Example:
cd ..
mkdir newname
cd newname

It will be convenient to place your CSIM installation under your home directory, and this will occur if you follow the regular directions by un-tar'ing there. Then you should be able to edit CSIM's setup file under csim/setup relative to you home directory. Here is a step-by-step procedure:
cd csim
dir
(You should see a listing with the setup file in it.)
(If not, you are in the wrong place.)
pwd
(Note the directory path pwd returns.)
vi setup
(Edit setup file to set directory to what pwd said.)
This procedure uses vi to edit the setup file because vi is usually available. You can move around with arrow keys. Use the x-key to delete characters. Type i to go into insert mode to add characters. Hit esc to get out of insert mode. Type :wq to write (save) the changes and quit. (If you mess up, type esc :q! to quit without saving and do-over.)
The key here is to read the comments in the setup file, and set the install location as it indicates by whatever pwd returned. You can then return to your home directory by typing: cd ..
Then you should be able to source the setup file from your home directory as: source csim/setup
It should say:
Using the Cygwin-PC version of CSIM
If not, the path is wrong.
You should add the source csim/setup command to the .bashrc file in you home directory. (.bashrc is the bash run-time command file. The .bashrc file can be used to make settings automatically whenever you start Cygwin.) Initially, there will be no .bashrc in your home directory. Just create it with a text editor (such as vi) and place source csim/setup on its own line within the file.
One final note: To be a valid text file, all text files must end with a carriage-return. All text-editors within Cygwin, such as vi, will automatically ensure this. However, we have found that some text-editors from Microsoft can create text files not ending with a return. Ending a file without a return can cause problems. For example, if you edit the license.txt file and do not have a return at the end of the line, it will not be accepted.

Q5: I cannot get graphics working under Cygwin. Can I test my CSIM installation in a purely textual mode?

A: Yes. Bring up the Cygwin terminal window by clicking the Cygwin icon or typing: c:\cygwin\startup.bat
from a DOS cmd window. This will put you into the Cygwin environment without X-windows graphics. From the Cygwin terminal window, try sourcing the CSIM setup file. You should then be able to run examples non-graphically, as in:
cd $CSIM_ROOT/demo_examples/demo0
csim -nongraphical test.sim
./sim.exe
You then should be at the simulator's textual prompt. Type: run
(Type q to quit.) If it works, you should see a bunch of simulation events scroll up the screen.
If this works, then this isolates your problem to graphics. If this does not work, then you have much bigger problems, such as a totally bad Cygwin install. Even the former case might indicate a few files did not get installed. Often these problems relate to a Cygwin installation step that was not followed carefully or a bad Cygwin source, and re-doing the Cygwin install (especially from a good source) clears it up. So I have to ask the required question: Did you use our Cygwin install disk or iso? And did you (or whoever did the install) follow the installation instructions to-the-letter? If not, you might try re-installing. Pay special attention to the All - Install discussion below.

Q6: When I try to run a demo I get this error: "The application has failed to start because libICE.dll Was not found. Re-installing the application may fix this problem." Should I attempt to re-install CSIM?

A: No. Messages about missing libICE.dll indicate missing Cygwin files. Recommend un-installing and re-installing Cygwin, but follow instructions carefully. See other notes about installation problems.

Q7a: When I try to start the X-server with startxwin.bat, it says command not found.

A: That indicates a bad (incomplete) Cygwin install. The startxwin.bat file should be under /usr/X11R6/bin.
...Q7b: I have the cygwin/usr folder but there is no X11R6/bin under it.

...A: Again, this also indicates a bad (incomplete) Cygwin install. Recommend un-installing and re-installing Cygwin, but follow instructions carefully. See notes below Cygwin installation problems below. When you do the Cygwin install, you should not need to select the X11 files, ... as long as you properly selected "Install All".
If for whatever reason you need to select X11 separately, then do it, but then you should also grab Xfree86, (and possibly something else), and that makes me suspicious that you would also need to grab the "development" libraries, which include the C compiler stuff, which is *not* part of the "default" install.
Notes about Cygwin install problems:
We have done many Cygwin installs. Trying different things on some. Basically we notice that selecting "Install All" is confusing and seems to cause the most problems. My first few times I thought I had selected it but had not done it properly. (Note that unfortunately "All - Default" is *not* the same as "All - Install". Default provides none of the needed packages. Go figure.) You want All - Install.
We have now helped many people install Cygwin. The cases fall into two distinct categories: (1) most install in one shot and everything works immediately as advertised, (2) but a few fall into a string of problems with missing items.
The Cygwin install process has a few steps which can be confusing the first time you try it.
In conclusion, I cannot not emphasize enough:
Your choice is to either spend 15 minutes reading our instructions and
following them TO-THE-LETTER and getting a good Cygwin install the first-time,
or spend days debugging and re-doing your installation, possibly never succeeding.

Q8: I'm having trouble getting a good Cygwin install. Many of the commands are not working, nor graphics applications.

A: That indicates a bad (incomplete) Cygwin install. (See above too.) The most critical spot in the Cygwin install process is selecting what to install. It comes up by default as: "All - default"
Sounds good, but if you selected that, it would explain the problems you are seeing. You need to toggle the little arrow until it says: "All - Install".
You need to be careful on some PC's there is a delay in responding each click. It goes off to configure or check things. It could look like it is on the right setting when you click next, meanwhile it might have been three clicks behind you in updating the display and you get the wrong selection. It's happened to me!
However, your cygwin installation may now be corrupted by the prior install attempts. It tries to maintain an install-state, but I have seen it get confused by aborted attempts. If so, do a Cygwin un-install, by repeating the setup.exe process, but answering un-install, and to be safe, regedit your registory and remove all references to Cygwin. Then repeat the install process from scratch.

Q: Is there a detailed reference for learning more about CYGWIN ?

A: Please see: Cygwin User's Guide

Q1:	Besides a compiler, what advantages does Cygwin bring to my PC?
A:	Some nice capabilities provided by Cygwin: Command-aliases - Substitute complex or frequently accessed commands with simple easily remembered names that can be used from anywhere. Ability to select text, copy, and cut&paste in text-windows or command-windows with mouse. Repeat commands with exclamation mark (! or bang) - !! repeats the last command, !-n repeats the nth previous command, and !n repeats the nth command. Command-line completion - Type only the first few letters of a file name, and hit <tab>. If the letters are enough to uniquely identify a single file, it will complete the file-name for you, but only up to the part that is unique. This avoids much typing (and typo's). Intelligent completion. Will stop where file name is ambiguous, instead of selecting random files, like newer MSwin shell does (which is cumbersome + very dangerous). On-line manuals - Type: man <any-command> ... And it will bring up a manual page describing how to use that command. Includes programming commands, as well. Command-line editing - Enables use of arrow and delete commands to alter or fix commands. Command history - a.) Up arrow to retrieve previous commands, b.) Type: history ... To see list of previous commands. c.) Short cuts: Type: !<command-number> or !<first-few-letter(s)> ... to repeat a previous command. Shows what directory you are in by typing: pwd (Print Working Directory). Allows you to resize the window to any arbitrary size by merely stretching the window border. Enables windows wider than 80-columns! Enables using the mouse to select or cut&paste text with single click. Simplifies cut&paste. Just select text with mouse, and paste by pressing middle-mouse button. (No combined menu or keyboard operations needed.) Text editors that are more capable than NotePad or Word, let you jump by words, lines, pages, or to specific line numbers, or kill lines quickly without repeatedly moving your hand off the keyboard. Ability to record, combine, and issue commands from flexible scipt files, minimizes need to learn and remember complex set of window operations or command sequences. Ability to make symbolic file/directory links, for example to save disk space. Ability to push directories onto a directory stack, to rapidly jump back&forth between or around multiple directories (pushd or pd). ... And many other work-saving capabilities. Note that everything is case-sensitive under Cygwin.

Q2:	Cygwin installs ok, but when I click the Cygwin icon, the bash shell window opens and then closes right away. What should I do?
A:	Try starting Cygwin from a DOS cmd window. It will provide further information. Report to us what it says. To bring up a DOS cmd window, click Start (lower left of screen), Accessories, Command Prompt. If you cannot find this, an alternate method is to select Start (lower left of screen), Run, and then type cmd. This should bring up a window to type commands and see responses. A good way to start Cygwin is to type: c:\cygwin\usr\X11R6\bin\startxwin.bat assuming that you installed Cygwin on your C: drive under cygwin. If you installed it elsewhere, they modify the above command accordingly. If this command works, you will soon see a new terminal window. It is the Cygwin window from which you can install and invoke CSIM. If not, you might see some error messages that indicate what the problem is. Report to us what it says so we can help diagnose it.

Q3:	Cygwin installs ok, and when I click the Cygwin icon, a terminal window appears. I then installed CSIM, but when I invoke the gui, I get the following error message: Error: Can't open display:
A:	This indicates that Cygwin's X-server is not running. It can be fixed by typing: startxwin.bat from within a Cygwin terminal window. You can test whether it started by typing: xterm & It should pop-up a new terminal window. If that does not work, it indicates a bad or incomplete Cygwin install. You need the X-server to run graphical applications under Cygwin. (See below for more info about correcting installation problems.)

Q4:	General category of questions: From within Cygwin, I do not see where I placed the CSIM files? When I try to source the CSIM setup file, it says File not found ? I would like to add the "source csim/setup" line to my .bashrc file but I have not found it? Where should the .bashrc file located?
A:	When you start Cygwin, it places you into a "home" directory. You can see where it is by typing: pwd (Which stands for "print working directory".) It should show something like: /home/yourname. Usually it is actually located under C:Cygwin\home\yourname, where yourname may be your user-name or possibly "unknown". And where the drive and top-level Cygwin directory are wherever you installed Cygwin. The key point is that under Cygwin, you start out under a home subdirectory. You can move anywhere by changing directories with cd. You can move outside the Cygwin directories by specifying a full absolute path including the drive letter. You can see the files in a directory with the dir -la command. A pitfall: You will have trouble if your home directory name contains spaces. It must be one word. If so, create a new home directory and use that. Example: cd .. mkdir newname cd newname It will be convenient to place your CSIM installation under your home directory, and this will occur if you follow the regular directions by un-tar'ing there. Then you should be able to edit CSIM's setup file under csim/setup relative to you home directory. Here is a step-by-step procedure: cd csim dir (You should see a listing with the setup file in it.) (If not, you are in the wrong place.) pwd (Note the directory path pwd returns.) vi setup (Edit setup file to set directory to what pwd said.) This procedure uses vi to edit the setup file because vi is usually available. You can move around with arrow keys. Use the x-key to delete characters. Type i to go into insert mode to add characters. Hit esc to get out of insert mode. Type :wq to write (save) the changes and quit. (If you mess up, type esc :q! to quit without saving and do-over.) The key here is to read the comments in the setup file, and set the install location as it indicates by whatever pwd returned. You can then return to your home directory by typing: cd .. Then you should be able to source the setup file from your home directory as: source csim/setup It should say: Using the Cygwin-PC version of CSIM If not, the path is wrong. You should add the source csim/setup command to the .bashrc file in you home directory. (.bashrc is the bash run-time command file. The .bashrc file can be used to make settings automatically whenever you start Cygwin.) Initially, there will be no .bashrc in your home directory. Just create it with a text editor (such as vi) and place source csim/setup on its own line within the file. One final note: To be a valid text file, all text files must end with a carriage-return. All text-editors within Cygwin, such as vi, will automatically ensure this. However, we have found that some text-editors from Microsoft can create text files not ending with a return. Ending a file without a return can cause problems. For example, if you edit the license.txt file and do not have a return at the end of the line, it will not be accepted.

Q5:	I cannot get graphics working under Cygwin. Can I test my CSIM installation in a purely textual mode?
A:	Yes. Bring up the Cygwin terminal window by clicking the Cygwin icon or typing: c:\cygwin\startup.bat from a DOS cmd window. This will put you into the Cygwin environment without X-windows graphics. From the Cygwin terminal window, try sourcing the CSIM setup file. You should then be able to run examples non-graphically, as in: cd $CSIM_ROOT/demo_examples/demo0 csim -nongraphical test.sim ./sim.exe You then should be at the simulator's textual prompt. Type: run (Type q to quit.) If it works, you should see a bunch of simulation events scroll up the screen. If this works, then this isolates your problem to graphics. If this does not work, then you have much bigger problems, such as a totally bad Cygwin install. Even the former case might indicate a few files did not get installed. Often these problems relate to a Cygwin installation step that was not followed carefully or a bad Cygwin source, and re-doing the Cygwin install (especially from a good source) clears it up. So I have to ask the required question: Did you use our Cygwin install disk or iso? And did you (or whoever did the install) follow the installation instructions to-the-letter? If not, you might try re-installing. Pay special attention to the All - Install discussion below.

Q6:	When I try to run a demo I get this error: "The application has failed to start because libICE.dll Was not found. Re-installing the application may fix this problem." Should I attempt to re-install CSIM?
A:	No. Messages about missing libICE.dll indicate missing Cygwin files. Recommend un-installing and re-installing Cygwin, but follow instructions carefully. See other notes about installation problems.

Q7a:	When I try to start the X-server with startxwin.bat, it says command not found.
A:	That indicates a bad (incomplete) Cygwin install. The startxwin.bat file should be under /usr/X11R6/bin.
...Q7b:	I have the cygwin/usr folder but there is no X11R6/bin under it.
...A:	Again, this also indicates a bad (incomplete) Cygwin install. Recommend un-installing and re-installing Cygwin, but follow instructions carefully. See notes below Cygwin installation problems below. When you do the Cygwin install, you should not need to select the X11 files, ... as long as you properly selected "Install All". If for whatever reason you need to select X11 separately, then do it, but then you should also grab Xfree86, (and possibly something else), and that makes me suspicious that you would also need to grab the "development" libraries, which include the C compiler stuff, which is not part of the "default" install. Notes about Cygwin install problems: We have done many Cygwin installs. Trying different things on some. Basically we notice that selecting "Install All" is confusing and seems to cause the most problems. My first few times I thought I had selected it but had not done it properly. (Note that unfortunately "All - Default" is not the same as "All - Install". Default provides none of the needed packages. Go figure.) You want *All - Install. We have now helped many people install Cygwin. The cases fall into two distinct categories: (1) most install in one shot and everything works immediately as advertised, (2) but a few fall into a string of problems with missing items. The Cygwin install process has a few steps which can be confusing the first time you try it. In conclusion, I cannot not emphasize enough:* Your choice is to either spend 15 minutes reading our instructions and following them TO-THE-LETTER and getting a good Cygwin install the first-time, or spend days debugging and re-doing your installation, possibly never succeeding.

Q8:	I'm having trouble getting a good Cygwin install. Many of the commands are not working, nor graphics applications.
A:	That indicates a bad (incomplete) Cygwin install. (See above too.) The most critical spot in the Cygwin install process is selecting what to install. It comes up by default as: "All - default" Sounds good, but if you selected that, it would explain the problems you are seeing. You need to toggle the little arrow until it says: "All - Install". You need to be careful on some PC's there is a delay in responding each click. It goes off to configure or check things. It could look like it is on the right setting when you click next, meanwhile it might have been three clicks behind you in updating the display and you get the wrong selection. It's happened to me! However, your cygwin installation may now be corrupted by the prior install attempts. It tries to maintain an install-state, but I have seen it get confused by aborted attempts. If so, do a Cygwin un-install, by repeating the setup.exe process, but answering un-install, and to be safe, regedit your registory and remove all references to Cygwin. Then repeat the install process from scratch.

Q:	Is there a detailed reference for learning more about CYGWIN ?
A:	Please see: Cygwin User's Guide