import winsup-2000-02-17 snapshot

1 files changed, 279 insertions, 0 deletions

diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml
new file mode 100644
index 000000000..7a24e5fa1
--- /dev/null
+++ b/winsup/doc/setup2.sgml
@@ -0,0 +1,279 @@
+<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) 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> Future changes to your NT registry 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 strace=0x1</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>
+<para>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>
+