CygwinGettingStarted

= Getting Started with Cygwin =

This page tells you how to:


 * install Cygwin
 * start a command prompt window running a Cygwin (i.e., bash) shell
 * install, update, or remove packaged utilities and libraries using Cygwin's setup.exe
 * understand how Cygwin works with Windows and how using Cygwin is different from using Linux
 * find further information on using Cygwin

Installing Cygwin
Installing Cygwin is simple, but you must have administrator privileges for the initial installation, and you must either have administratior privileges or be the owner of the Cygwin registry entries to install Cygwin packages.

If you normally run with limited user privileges: Managing your Cygwin installation is easier if you are the owner of the Cygwin entries in the Windows registry.

The way to ensure this is to: 1. Log out of your usual account 2. Log into an account with administrator privileges and use the control panel to give your usual account administrator privileges 3. Switch to your usual account and install Cygwin using the procedure below 4. Log out of your usual account 5. Log into your administrator account and change your usual account back to limited user If you do this, you will own the Cygwin entries in the registry. If you do not do this, you will need administrator privileges to install Cygwin packages.

There is also an option during the installation process to install Cygwin for "Just Me". This may be easier, but I have not tried it. You will still need administrator privileges if want to install a USRP.

To install Cygwin:

1. Go to http://www.cygwin.com 2. Click on "Mirror Sites" in the lefthand column and note the two mirror sites nearest you 3. Go back to http://www.cygwin.com and click on "Install Cygwin now" 4. Go ahead and run setup.exe ; the default settings are fine, but you may want to make the "Local Package Directory" a subdirectory of your "Root Directory" (e.g., "C:\cygwin\setup") 5. When asked to choose a mirror site, choose one you selected above; if that one doesn't work, try the other one 6. Keep clicking "Next" until Cygwin has been installed; you probably want to click the boxes to put an icon on your desktop and add Cygwin to your startup menu

For convenience you may want to go back to http://www.cygwin.com, right-click on "Install Cygwin now" again, and save a copy of setup.exe in a convenient place (e.g., C:\cygwin\setup\setup.exe ). You will be running setup.exe repeatedly to download and update Cygwin packages.

Starting a Cygwin Window
Most of the work in Cygwin is done by entering commands into a command prompt window. The commands you enter are interpreted by a GNU bash shell. You can start a Cygwin command window in one of the following ways:


 * Double-click on the Cygwin icon on your desktop (if setup.exe put one there)
 * Find Cygwin in your Windows "Start" menu (under "All Programs")
 * If necessary, you can use Windows Explorer to navigate the the Cygwin root directory (e.g., "My Computer" > "Local Disk" > "Cygwin") and double-click on cygwin.bat ; or you can right-click on cygwin.bat and select "Send To" -> "Desktop" to make a shortcut for next time

Using setup.exe
One thing that makes Cygwin convenient is the ease of selecting and installing optional software packages with setup.exe. You can run setup.exe from the web, from a command prompt, or from Windows Explorer, depending on what privileges you have.

If you have administrator privileges or if you own the Cygwin registry entries, you can either:


 * Go to http://www.cygwin.com and click the "Install Cygwin now" icon; or
 * Run setup.exe from your local disk (e.g., /setup/setup.exe ) if you saved a copy there; or
 * Use Windows Explorer to navigate to the directory containing your saved setup.exe (if you have one) and double-click

If you have access to an account with administrator privileges and a non-blank password, you can:

1. Use Windows Explorer to navigate to the directory containing your saved setup.exe (if you have one) and double-click; then 2. Enter the account name and password when requested

Once Cygwin Setup is running, you can tell it to use the default values (Install from Internet; same root directory, "install for" setting, and default text file type as on your initial install; same local package directory; same internet connection; and same download site) until you get to the "Select Packages" window.

The "Select Packages" window is very powerful but is not immediately intuitive to all users, has no "Help" button, and the pop-up documentation may go away before you can finish reading it. The most important thing to know is that the "View" button cycles through several displays of packages:

The "Current" column shows the version number for each package you have already installed while the "New" column lets you select select a package to be installed, reinstalled, uninstalled, or kept unchanged. Normally, you will choose a convenient View (e.g., "Category" or "Not Installed") to select packages then chose the "Partial" view to verify the changes you are about to make. Clicking "Next" will make the changes you selected.
 * Category: click the "+" to see what is in a category
 * Full: everything in alphabetical order
 * Partial: your current "to do" list, including packages you have selected, other packages required by your selections, and updates to packages you installed previously
 * Up to Date: a list of packages you already have
 * Not Installed: a list of packages you don't already have

Cygwin vs. Linux; Cygwin and Windows
Although Cygwin uses a bash shell and many of the same commands and programs as Linux, it is still running under the Windows operating system and must accommodate the needs and limitations of that system. Some of the important consequences are:

File and Path Names

 * Windows remembers the case of characters in filenames, but ignores the case when accessing files; any files sent back to a Linux system will use the case you specify, so it pays not to be too sloppy
 * Windows uses "\" to separate directories in a path, but in Cygwin you must use "/" (the bash shell uses "\" as an escape character)
 * Path names starting with "/" are relative to the Cygwin root directory (i.e., C:/cygwin for a default installation)
 * Non-Cygwin files can be accessed with their full Windows path (starting with the drive letter) using "/" instead of "\"; if a path includes spaces, enclose it in double quotes (e.g., ls "C:/Program Files/SDCC" )
 * The "C:" in a path should be replaced with "/cygdrive/c" when the ":" might cause a problem (e.g., PATH="$PATH:/cygdrive/c/Program Files/SDCC" )
 * To access Cygwin files from Windows, start by navigating to your Cygwin installation directory (e.g., "My Computer" > "Local Disk(C:)" > "cygwin" in a default installation)
 * Executable files on Windows have names ending in .exe but you can reference them in Cygwin without the .exe ; thus the ls command actually runs /bin/ls.exe and ls /bin/ls shows the file /bin/ls even though the file is actually named /bin/ls.exe

End-Of-Line Conventions; Binary and Text Files
In Linux, lines in a text file are separated by a newline characters (ASCII Ctrl-J, often shown as !^J, or '\n' in C). In Windows, lines are separated by carriage return and newline characters (the two-character sequence ^M^J or "\r\n" in C). Many of the programs you will use with Cygwin don't care, but some do. When you see ^M popping up you know that there are Windows-style files around. When you look at a file in Windows Notepad and see all the lines running together with little boxes between them you know you are looking at a Linux-style file.

In general, when working on programs with Cygwin it is better to stick with the Linux \n line separators when possible. In particular, the Cygwin autoconf utility has problems with some .m4 files that include the ^M characters as line separators. This also means that it is better to use a Cygwin version of the Subversion program rather than a Windows version---the Windows version will give you the extra ^M characters as line separators. This also means that it is better to use a Cygwin version of the Subversion program rather than a Windows version---the Windows version will give you the extra ^M characters with some files in some SVN repositories.

Permissions
The Linux su and sudo commands do not work on Cygwin. On Windows, access to some files and to parts of the Windows registry (a database of system configuration information) is limited to accounts with administrator privileges. Most files in Cygwin can be accessed without administrator privileges.

Many Windows systems are set up with administrator privileges on normal user accounts, but many users with Unix or Linux backgrounds prefer to work mostly as what Windows calls limited users. If you normally work in a limited user account and you need to access resources that require administrator privileges, you must to one of the following:


 * Use an account with administrator privileges to access the resources, or
 * Use an account with administrator privileges to temporarily give administrator privileges to your account; you will need to log into your account again for the changes to take effect, or
 * Most programs can be run as another user by right-clicking on them (in Windows Explorer) and selecting "Run as..." (some programs, such as Cygwin setup.exe, automatically offer to let you run as another user); in order to use this feature, you need access to an account with administrator privileges that has a non-blank password

Where to Find More Infomation on Using Cygwin
The best places to start are the Cygwin FAQ and User's Guide. Both are available at, and they should also be installed on your machine (look under "Cygwin" in your "Start" -> "All Programs" menu). The User's Guide includes sections for Windows users who are new to Linux and Linux users who are new to Windows.