newlib-cygwin/winsup/doc/setup2.sgml

<sect1 id="setup-dir"><title>Directory Structure</title>

<para>
Cygwin knows how to emulate a standard UNIX directory structure, to
some extent.  This is done through the use of mount tables that map
Win32 paths to POSIX ones.  The mount table may be set up and modified
with the <command>mount</command> command. This section explains how
to properly organize the structure. </para>

<para> When you set up the system you should decide where you want the
root to be mapped.  Possible choices are the root of your Windows
system, such as
<filename>c:</filename> or a directory such as
<filename>c:\progra~1\root</filename>.
</para>

<para>
Execute the following commands inside bash as it is difficult to
change the position of the root from the Windows command prompt.
Changing the mount points may invalidate <EnVar>PATH</EnVar>, if this
happens simply exit and relaunch bash.  Create the directory if
needed, then <command>umount /</command> the current root and 
<command>mount</command> it in its new place.  You also have to decide if
you want to use text or binary mode.  
</para>

<para>
Next, create the traditional main UNIX directories, with
the following command (in some shells it is necessary to issue
separate <command>mkdir</command> commands, each with a single
argument).
</para>

<screen>
<prompt>/$</prompt> <userinput>mkdir /tmp /bin /etc /var /usr</userinput>
</screen>

<para>
Next we will initialize the content of these directories.
</para>

<para>
You should make sure that you always have a valid
<filename>/tmp</filename> directory.  If you want to avoid creating a
real <filename>/tmp</filename>, you can use the
<command>mount</command> utility to point <filename>/tmp</filename> to
another directory, such as <filename>c:\tmp</filename>, or create a
symbolic link <filename>/tmp</filename> to point to such a directory.
</para>

<para>
The <filename>/bin</filename> directory should contain the shell
<filename>sh.exe</filename>.  You have three choices.  The first is to
copy this program from the Cygnus <filename>bin</filename> directory.
The second is to use <command>mount</command> to mount the Cygnus
<filename>bin</filename> directory to <filename>/bin</filename> (the
advantage of this approach is that your <envar>PATH</envar> will be
shorter inside bash).  The third is to make <filename>/bin</filename> a
symbolic link to the Cygnus <filename>bin</filename> directory.
</para>

<para>
Note that Cygwin comes with two shells: <command>bash.exe</command> and
<command>sh.exe</command>, which is based on <command>ash</command>.  The
system is faster when <command>ash</command> is used as the 
non-interactive shell. 
The only functionality supported in <command>ash</command> is that 
of the traditional <command>sh</command>.  
In case of trouble with <command>ash</command> make
<command>sh.exe</command> point to <command>bash.exe</command>.
</para>

<para>
We now turn to <filename>/etc</filename>.  You may want to copy in it
the <filename>termcap</filename> file from the Cygnus
<filename>etc</filename> directory, although the defaults built into
the programs suffice for the normal console.  You may also use
<command>mount</command> or create as symbolic link to the Cygnus
<filename>etc</filename>, just as for <filename>/bin</filename>
above.
</para>

<para> Under Windows NT, if you want to create 
<filename>/etc/passwd</filename> and <filename>/etc/group</filename> 
(i.e. so that <command>whoami</command> works and 
<command>ls -l</command> replaces the UID with a name) based on the accounts local to the machine, just do this:
</para>

<screen>
<prompt>/$</prompt> <userinput>cd /etc</userinput>
<prompt>/etc$</prompt> <userinput>mkpasswd -l > /etc/passwd</userinput>
<prompt>/etc$</prompt> <userinput>mkgroup -l > /etc/group</userinput>
</screen>

<para>If you are logging in based on an NT network domain, and want to
also create entries in <filename>/etc/passwd</filename> and
<filename>/etc/group</filename> based on all the accounts in the
domain, then after creating local entries do this:
</para>

<screen>
<prompt>/$</prompt> <userinput>cd /etc</userinput>
<prompt>/etc$</prompt> <userinput>mkpasswd -d >> /etc/passwd</userinput>
<prompt>/etc$</prompt> <userinput>mkgroup -d >> /etc/group</userinput>
</screen>

<para>Alternatively, to add only your account to the passwd file,
assuming your NT name is "my_ntusername", instead of the above
<command>mkpasswd</command> you should do:
</para>
 
<screen>
<prompt>/$</prompt> <userinput>cd /etc</userinput>
<prompt>/etc$</prompt> <userinput>mkpasswd -d | grep my_ntusername >> /etc/passwd</userinput>
</screen>


<para> Future changes to your NT registry or network domain will NOT be reflected in
<filename>/etc/passwd</filename> or <filename>/etc/group </filename> after
this so you may want to regenerate these files periodically.  Under Windows
9x, you can create and edit these files with a text editor.  </para>

<para>
The <command>who</command> command requires the
<filename>/var/run/utmp</filename> to exist.
Create it if you wish.
The system also logs information in <filename>/var/log/wtmp</filename>,
if it exists.
</para>

<para>
The <filename>/usr</filename> directory is not used by the Cygwin
system but it is a standard place to install optional packages.
</para>

<para>
You may also want to mount directories such as <filename>/a</filename>
and <filename>/d</filename> to refer to your local and network drives.
</para>

<para>
You do not need to create <filename>/dev</filename> in order to set up
mounts for devices such as <filename>/dev/null</filename> as these
are already automatically simulated inside the Cygwin library.
</para>

</sect1>

<sect1 id="setup-env"><title>Environment Variables</title>

<para>
Before starting bash, you must set some environment variables, some of
which can also be set or modified inside bash.  Cygnus provides you
with a .bat file where the most important ones are set before bash in
launched.  This is the safest way to launch bash initially.  The .bat
file is installed by default in
<filename>\cygnus\cygwin-b20/cygnus.bat</filename> and pointed to in
the Start Menu.  You can edit it to your liking.
</para>

<para>
The <envar>CYGWIN</envar> variable is used to configure many global 
settings for the Cygwin
runtime system.  Initially you can leave <envar>CYGWIN</envar> unset
or set it to <literal>tty</literal> (e.g. to support job control with ^Z 
etc...) using a syntax like this in the DOS shell, before launching bash.
</para>

<screen>
<prompt>C:\Cygnus\&gt;</prompt> <userinput>set CYGWIN=tty notitle glob</userinput>
</screen>

<para>
The <envar>PATH</envar> environment variable is used by Cygwin
applications as a list of directories to search for executable files
to run.  This environment variable is converted from Windows format
(e.g. <filename>C:\WinNT\system32;C:\WinNT</filename>) to UNIX format
(e.g., <filename>/WinNT/system32:/WinNT</filename>) when a Cygwin
process first starts.
Set it so that it contains at least the Cygnus
<filename>bin</filename> directory
<filename>C:\cygnus\cygwin-b20\H-i586-cygwin32\bin</filename> before
launching bash.
</para>

<para> 
The <envar>HOME</envar> environment variable is used by many programs to
determine the location of your home directory and we recommend that it be
defined.  This environment variable is also converted from Windows format
when a Cygwin process first starts.  Set it to point to your home directory
before launching bash. 
</para>

<para>
<command>make</command> uses an environment variable
<envar>MAKE_MODE</envar> to decide if it uses
<filename>command.com</filename> or <filename>/bin/sh</filename> to
run command lines.  If you are getting strange errors from
<command>make</command> about "/c not found", set
<envar>MAKE_MODE</envar> to <literal>UNIX</literal> at the command
prompt or in bash.
</para>

<screen>
<prompt>C:\Cygnus\&gt;</prompt> <userinput>set MAKE_MODE=UNIX</userinput>

<prompt>/Cygnus$</prompt> <userinput>export MAKE_MODE=UNIX</userinput>
</screen>

<para>
The <envar>TERM</envar> environment variable specifies your terminal
type.  You can set it to <literal>cygwin</literal>.
</para>

<para>The <envar>LD_LIBRARY_PATH</envar> environment variable is
used by the Cygwin function <function>dlopen ()</function> as a list
of directories to search for .dll files to load.  This environment
variable is converted from Windows format to UNIX format
when a Cygwin process first starts.
Most Cygwin applications do not make use of the
<function>dlopen ()</function> call and do not need this variable.
</para>

</sect1>

<sect1 id="setup-files"><title>Customizing bash</title>

<para>
To set bash up so that cut and paste work properly, click on the
"Properties" button of the window, then on the "Misc" tab.  Make sure
that "Quick Edit" is checked and "Fast Pasting" isn't.  These settings
will be remembered next time you run bash from that
shortcut. Similarly you can set the working directory inside the
"Program" tab. The entry "%HOME%" is valid.
</para>

<para>
Your home directory should contain three initialization files
that control the behavior of bash.  They are
<filename>.profile</filename>, <filename>.bashrc</filename> and
<filename>.inputrc</filename>.  These initialization files will only
be read if <envar>HOME</envar> is defined before starting bash.
</para>

<para>
<filename>.profile</filename> (other names are also valid, see the bash man
page) contains bash commands.  It is executed when bash is started as login
shell, e.g. from the command <command>bash --login</command> (the provided
.bat file does not set the switch).  This is a useful place to define and
export environment variables and bash functions that will be used by bash
and the programs invoked by bash.  It is a good place to redefine
<envar>PATH</envar> if needed.  We recommend adding a ":." to the end of
<envar>PATH</envar> to also search the current working directory (contrary
to DOS, the local directory is not searched by default).  Also to avoid
delays you should either <command>unset</command> <envar>MAILCHECK</envar> 
or define <envar>MAILPATH</envar> to point to your existing mail inbox.
</para>

<para>
<filename>.bashrc</filename> is similar to
<filename>.profile</filename> but is executed each time an interactive
bash shell is launched.  It serves to define elements that are not
inherited through the environment, such as aliases. If you do not use
login shells, you may want to put the contents of
<filename>.profile</filename> as discussed above in this file
instead.
</para>

<para>
<screen>
shopt -s nocaseglob
</screen>
will allow bash to glob filenames in a case-insensitive manner.
Note that <filename>.bashrc</filename> is not called automatically for login 
shells. You can source it from <filename>.profile</filename>.
</para>

<para>
<filename>.inputrc</filename> controls how programs using the readline
library (including bash) behave.  It is loaded automatically.  The
full details are in the <filename>readline.info</filename>. 
Due to a bug in the current readline version, 
<filename>.inputrc</filename> cannot contain \r,
even on text mounted systems.
Consider the following settings:
<screen>
# Make Bash 8bit clean
set meta-flag on
set convert-meta off
set output-meta on
# Ignore case while completing
set completion-ignore-case on
</screen>
The first three commands allow bash to display 8-bit characters,
useful for languages with accented characters.  The last line makes
filename completion case insensitive, which can be convenient in a
Windows environment.
</para>

</sect1>