newlib/winsup/doc/setup2.sgml

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

<para>
Before starting bash, you may set some environment variables.  A .bat
file is provided 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 in the root directory that you specified during setup
and pointed to in the Start Menu under the "Cygwin" option.  You can
edit it this file 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:\&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:\Windows\system32;C:\Windows</filename>) to UNIX format
(e.g., <filename>/cygdrive/c/Windows/system32:/cygdrive/c/Windows</filename>)
when a Cygwin process first starts.
Set it so that it contains at least the <filename>x:\cygwin\bin</filename>
directory where "<filename>x:\cygwin</filename> is the "root" of your
cygwin installation if you wish to use cygwin tools outside of bash.
This is usually done by the batch file you're starting your shell with.
</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.  It's usually set in the shell
profile scripts in the /etc directory.
</para>

<para>
The <envar>TERM</envar> environment variable specifies your terminal
type.  It is automatically set to <literal>cygwin</literal> if you have
not set it to something else.
</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-maxmem"><title>Changing Cygwin's Maximum Memory</title>

<para>
Cygwin's heap is extensible.  However, it does start out at a fixed size
and attempts to extend it may run into memory which has been previously
allocated by Windows.  In some cases, this problem can be solved by
adding an entry in the either the <literal>HKEY_LOCAL_MACHINE</literal>
(to change the limit for all users) or
<literal>HKEY_CURRENT_USER</literal> (for just the current user) section
of the registry.  </para>

<para>
Add the <literal>DWORD</literal> value <literal>heap_chunk_in_mb</literal> 
and set it to the desired memory limit in decimal MB. It is preferred to do 
this in Cygwin using the <command>regtool</command> program included in the 
Cygwin package.
(For more information about <command>regtool</command> or the other Cygwin 
utilities, see <xref linkend="using-utils"></xref> or use each the
<literal>--help</literal> option of each util.)  You should always be careful 
when using <command>regtool</command> since damaging your system registry can 
result in an unusable system.  This example sets memory limit to 1024 MB:

<screen>
regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
regtool -v list /HKLM/Software/Cygwin
</screen>
</para>

<para>
Exit all running Cygwin processes and restart them. Memory can be allocated up 
to the size of the system swap space minus any the size of any running 
processes. The system swap should be at least as large as the physically 
installed RAM and can be modified under the System category of the 
Control Panel.  
</para>

<para>
Here is a small program written by DJ Delorie that tests the 
memory allocation limit on your system:

<screen>
main()
{
  unsigned int bit=0x40000000, sum=0;
  char *x;
  
  while (bit > 4096) 
  {
    x = malloc(bit);
    if (x)
    sum += bit;
    bit >>= 1;
  }
  printf("%08x bytes (%.1fMb)\n", sum, sum/1024.0/1024.0);
  return 0;
}
</screen>

You can compile this program using:
<screen>
gcc max_memory.c -o max_memory.exe
</screen>

Run the program and it will output the maximum amount of allocatable memory.
</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 "QuickEdit mode" and "Insert mode" are checked.  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, but requires that you set <envar>HOME</envar> in
the Windows environment.
</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>.  The Cygwin base installation creates
stub files when you start bash for the first time.</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>.
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 <command>bash</command>) behave.  It is loaded
automatically.  For full details see the <literal>Function and Variable
Index</literal> section of the GNU <systemitem>readline</systemitem> manual.
Consider the following settings:
<screen>
# Ignore case while completing
set completion-ignore-case on
# Make Bash 8bit clean
set meta-flag on
set convert-meta off
set output-meta on
</screen>
The first command makes filename completion case insensitive, which can
be convenient in a Windows environment.  The next three commands allow
<command>bash</command> to display 8-bit characters, useful for
languages with accented characters.  Note that tools that do not use
<systemitem>readline</systemitem> for display, such as
<command>less</command> and <command>ls</command>, require additional
settings, which could be put in your <filename>.bashrc</filename>:
<screen>
alias less='/bin/less -r'
alias ls='/bin/ls -F --color=tty --show-control-chars'
</screen>
</para>

</sect1>