diff options
Diffstat (limited to 'winsup/doc/setup2.sgml')
| -rw-r--r-- | winsup/doc/setup2.sgml | 279 |
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\></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\></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> + |