en/handbook/hb-working-variables.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-variables.xml,v 1.16 2005/09/28 10:30:37 neysx Exp $ -->

<sections>

<version>1.13</version>
<date>2005-09-28</date>

<section>
<title>Environment Variables?</title>
<subsection>
<title>What they are</title>
<body>

<p>
An environment variable is a named object that contains information used by one
or more applications. Many users (and especially those new to Linux) find this
a bit weird or unmanageable. However, this is a mistake: by using environment
variables one can easily change a configuration setting for one or more
applications.
</p>

</body>
</subsection>
<subsection>
<title>Important Examples</title>
<body>

<p>
The following table lists a number of variables used by a Linux system and
describes their use. Example values are presented after the table.
</p>

<table>
<tr>
  <th>Variable</th>
  <th>Description</th>
</tr>
<tr>
  <ti>PATH</ti>
  <ti>
    This variable contains a colon-separated list of directories in which your 
    system looks for executable files. If you enter a name of an executable 
    (such as <c>ls</c>, <c>rc-update</c> or <c>emerge</c>) but this executable 
    is not located in a listed directory, your system will not execute it 
    (unless you enter the full path as command, such as <c>/bin/ls</c>).
  </ti>
</tr>
<tr>
  <ti>ROOTPATH</ti>
  <ti>
    This variable has the same function as <c>PATH</c>, but this one only lists
    the directories that should be checked when the root-user enters a command.
  </ti>
</tr>
<tr>
  <ti>LDPATH</ti>
  <ti>
    This variable contains a colon-separated list of directories in which the
    dynamical linker searches through to find a library.
  </ti>
</tr>
<tr>
  <ti>MANPATH</ti>
  <ti>
    This variable contains a colon-separated list of directories in which the
    <c>man</c> command searches for the man pages.
  </ti>
</tr>
<tr>
  <ti>INFODIR</ti>
  <ti>
    This variable contains a colon-separated list of directories in which the
    <c>info</c> command searches for the info pages.
  </ti>
</tr>
<tr>
  <ti>PAGER</ti>
  <ti>
    This variable contains the path to the program used to list the contents of
    files through (such as <c>less</c> or <c>more</c>).
  </ti>
</tr>
<tr>
  <ti>EDITOR</ti>
  <ti>
    This variable contains the path to the program used to change the contents
    of files with (such as <c>nano</c> or <c>vi</c>).
  </ti>
</tr>
<tr>
  <ti>KDEDIRS</ti>
  <ti>
    This variable contains a colon-separated list of directories which contain
    KDE-specific material.
  </ti>
</tr>
<tr>
  <ti>CLASSPATH</ti>
  <ti>
    This variable contains a colon-separated list of directories which contain
    Java classes.
  </ti>
</tr>
<tr>
  <ti>CONFIG_PROTECT</ti>
  <ti>
    This variable contains a <e>space</e>-delimited list of directories which
    should be protected by Portage during updates.
  </ti>
</tr>
<tr>
  <ti>CONFIG_PROTECT_MASK</ti>
  <ti>
    This variable contains a <e>space</e>-delimited list of directories which
    should not be protected by Portage during updates. 
  </ti>
</tr>
</table>

<p>
Below you will find an example definition of all these variables:
</p>

<pre caption="Example definitions">
PATH="/bin:/usr/bin:/usr/local/bin:/opt/bin:/usr/games/bin"
ROOTPATH="/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin"
LDPATH="/lib:/usr/lib:/usr/local/lib:/usr/lib/gcc-lib/i686-pc-linux-gnu/3.2.3"
MANPATH="/usr/share/man:/usr/local/share/man"
INFODIR="/usr/share/info:/usr/local/share/info"
PAGER="/usr/bin/less"
EDITOR="/usr/bin/vim"
KDEDIRS="/usr"
CLASSPATH="/opt/blackdown-jre-1.4.1/lib/rt.jar:."
CONFIG_PROTECT="/usr/X11R6/lib/X11/xkb /opt/tomcat/conf \
                /usr/kde/3.1/share/config /usr/share/texmf/tex/generic/config/ \
                /usr/share/texmf/tex/platex/config/ /usr/share/config"
CONFIG_PROTECT_MASK="/etc/gconf
</pre>

</body>
</subsection>
</section>
<section>
<title>Defining Variables Globally</title>
<subsection>
<title>The /etc/env.d Directory</title>
<body>

<p>
To centralise the definitions of these variables, Gentoo introduced the
<path>/etc/env.d</path> directory. Inside this directory you will find a number
of files, such as <path>00basic</path>, <path>05gcc</path>, etc. which contain
the variables needed by the application mentioned in their name.
</p>

<p>
For instance, when you installed <c>gcc</c>, a file called <path>05gcc</path>
was created by the ebuild which contains the definitions of the following
variables:
</p>

<pre caption="/etc/env.d/05gcc">
PATH="/usr/i686-pc-linux-gnu/gcc-bin/3.2"
ROOTPATH="/usr/i686-pc-linux-gnu/gcc-bin/3.2"
MANPATH="/usr/share/gcc-data/i686-pc-linux-gnu/3.2/man"
INFOPATH="/usr/share/gcc-data/i686-pc-linux-gnu/3.2/info"
CC="gcc"
CXX="g++"
LDPATH="/usr/lib/gcc-lib/i686-pc-linux-gnu/3.2.3"
</pre>

<p>
Other distributions tell you to change or add such environment variable
definitions in <path>/etc/profile</path> or other locations. Gentoo on the other
hand makes it easy for you (and for Portage) to maintain and manage the
environment variables without having to pay attention to the numerous files that
can contain environment variables.
</p>

<p>
For instance, when <c>gcc</c> is updated, the <path>/etc/env.d/05gcc</path> file
is updated too without requesting any user-interaction. 
</p>

<p>
This not only benefits Portage, but also you, as user. Occasionally you might
be asked to set a certain environment variable system-wide. As an example we
take the <c>http_proxy</c> variable. Instead of messing about with
<path>/etc/profile</path>, you can now just create a file
(<path>/etc/env.d/99local</path>) and enter your definition(s) in it:
</p>

<pre caption="/etc/env.d/99local">
http_proxy="proxy.server.com:8080"
</pre>

<p>
By using the same file for all your variables, you have a quick overview on the
variables you have defined yourself. 
</p>

</body>
</subsection>
<subsection>
<title>The env-update Script</title>
<body>

<p>
Several files in <path>/etc/env.d</path> define the <c>PATH</c> variable. This
is not a mistake: when you run <c>env-update</c>, it will append the several
definitions before it updates the environment variables, thereby making it easy
for packages (or users) to add their own environment variable settings without
interfering with the already existing values.
</p>

<p>
The <c>env-update</c> script will append the values in the alphabetical order
of the <path>/etc/env.d</path> files. The file names must begin with two
decimal digits.
</p>

<pre caption="Update order used by env-update">
         00basic        99kde-env       99local
     +-------------+----------------+-------------+
PATH="/bin:/usr/bin:/usr/kde/3.2/bin:/usr/local/bin"
</pre>

<p>
The concatenation of variables does not always happen, only with the following
variables: <c>KDEDIRS</c>, <c>PATH</c>, <c>CLASSPATH</c>, <c>LDPATH</c>,
<c>MANPATH</c>, <c>INFODIR</c>, <c>INFOPATH</c>, <c>ROOTPATH</c>,
<c>CONFIG_PROTECT</c>, <c>CONFIG_PROTECT_MASK</c>, <c>PRELINK_PATH</c> and
<c>PRELINK_PATH_MASK</c>. For all other variables the latest defined value (in
alphabetical order of the files in <path>/etc/env.d</path>) is used.
</p>

<p>
When you run <c>env-update</c>, the script will create all environment variables
and place them in <path>/etc/profile.env</path> (which is used by
<path>/etc/profile</path>). It will also extract the information from the
<c>LDPATH</c> variable and use that to create <path>/etc/ld.so.conf</path>.
After this, it will run <c>ldconfig</c> to recreate the
<path>/etc/ld.so.cache</path> file used by the dynamical linker.
</p>

<p>
If you want to notice the effect of <c>env-update</c> immediately after you run
it, execute the following command to update your environment. Users who have
installed Gentoo themselves will probably remember this from the installation
instructions:
</p>

<pre caption="Updating the environment">
# <i>env-update &amp;&amp; source /etc/profile</i>
</pre>

<note>
The above command only updates the variables in your current terminal,
<e>new</e> consoles, and their children. Thus, if you are working in X11, you
will need to either type <c>source /etc/profile</c> in every new terminal you
open or restart X so that all new terminals source the new variables. If you
use a login manager, become root and type <c>/etc/init.d/xdm restart</c>. If
not, you will need to logout and log back in for X to spawn children with the
new variable values.
</note>

</body>
</subsection>
</section>
<section>
<title>Defining Variables Locally</title>
<subsection>
<title>User Specific</title>
<body>

<p>
You do not always want to define an environment variable globally. For instance,
you might want to add <path>/home/my_user/bin</path> and the current working
directory (the directory you are in) to the <c>PATH</c> variable
but don't want all other users on your system to have that in their <c>PATH</c>
too. If you want to define an environment variable locally, you should use
<path>~/.bashrc</path> or <path>~/.bash_profile</path>:
</p>

<pre caption="Extending PATH for local usage in ~/.bashrc">
<comment>(A colon followed by no directory is treated as the current working directory)</comment>
PATH="${PATH}:/home/my_user/bin:"
</pre>

<p>
When you relogin, your <c>PATH</c> variable will be updated.
</p>

</body>
</subsection>
<subsection>
<title>Session Specific</title>
<body>

<p>
Sometimes even stricter definitions are requested. You might want to be able to
use binaries from a temporary directory you created without using the path to
the binaries themselves or editing <path>~/.bashrc</path> for the short time
you need it.
</p>

<p>
In this case, you can just define the <c>PATH</c> variable in your current
session by using the <c>export</c> command. As long as you don't log out, the
<c>PATH</c> variable will be using the temporary settings.
</p>

<pre caption="Defining a session-specific environment variable">
# <i>export PATH="${PATH}:/home/my_user/tmp/usr/bin"</i>
</pre>

</body>
</subsection>
</section>
</sections>
1	swift	1.5	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4	swift	1.1	<!-- The content of this document is licensed under the CC-BY-SA license -->
5	neysx	1.17	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6	swift	1.1
7	neysx	1.17	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-variables.xml,v 1.16 2005/09/28 10:30:37 neysx Exp $ -->
8	swift	1.1
9			<sections>
10	swift	1.9
11	neysx	1.16	<version>1.13</version>
12			<date>2005-09-28</date>
13	swift	1.9
14	swift	1.1	<section>
15			<title>Environment Variables?</title>
16			<subsection>
17			<title>What they are</title>
18			<body>
19
20	swift	1.2	<p>
21			An environment variable is a named object that contains information used by one
22	neysx	1.8	or more applications. Many users (and especially those new to Linux) find this
23			a bit weird or unmanageable. However, this is a mistake: by using environment
24			variables one can easily change a configuration setting for one or more
25			applications.
26	swift	1.2	</p>
27	swift	1.1
28			</body>
29			</subsection>
30			<subsection>
31			<title>Important Examples</title>
32			<body>
33
34	swift	1.2	<p>
35			The following table lists a number of variables used by a Linux system and
36			describes their use. Example values are presented after the table.
37			</p>
38
39			<table>
40			<tr>
41			<th>Variable</th>
42			<th>Description</th>
43			</tr>
44			<tr>
45			<ti>PATH</ti>
46			<ti>
47			This variable contains a colon-separated list of directories in which your
48			system looks for executable files. If you enter a name of an executable
49			(such as <c>ls</c>, <c>rc-update</c> or <c>emerge</c>) but this executable
50			is not located in a listed directory, your system will not execute it
51			(unless you enter the full path as command, such as <c>/bin/ls</c>).
52			</ti>
53			</tr>
54			<tr>
55			<ti>ROOTPATH</ti>
56			<ti>
57			This variable has the same function as <c>PATH</c>, but this one only lists
58			the directories that should be checked when the root-user enters a command.
59			</ti>
60			</tr>
61			<tr>
62			<ti>LDPATH</ti>
63			<ti>
64			This variable contains a colon-separated list of directories in which the
65			dynamical linker searches through to find a library.
66			</ti>
67			</tr>
68			<tr>
69			<ti>MANPATH</ti>
70			<ti>
71			This variable contains a colon-separated list of directories in which the
72			<c>man</c> command searches for the man pages.
73			</ti>
74			</tr>
75			<tr>
76			<ti>INFODIR</ti>
77			<ti>
78			This variable contains a colon-separated list of directories in which the
79			<c>info</c> command searches for the info pages.
80			</ti>
81			</tr>
82			<tr>
83			<ti>PAGER</ti>
84			<ti>
85			This variable contains the path to the program used to list the contents of
86			files through (such as <c>less</c> or <c>more</c>).
87			</ti>
88			</tr>
89			<tr>
90			<ti>EDITOR</ti>
91			<ti>
92			This variable contains the path to the program used to change the contents
93			of files with (such as <c>nano</c> or <c>vi</c>).
94			</ti>
95			</tr>
96			<tr>
97			<ti>KDEDIRS</ti>
98			<ti>
99			This variable contains a colon-separated list of directories which contain
100			KDE-specific material.
101			</ti>
102			</tr>
103			<tr>
104			<ti>CLASSPATH</ti>
105			<ti>
106			This variable contains a colon-separated list of directories which contain
107			Java classes.
108			</ti>
109			</tr>
110			<tr>
111			<ti>CONFIG_PROTECT</ti>
112			<ti>
113			This variable contains a <e>space</e>-delimited list of directories which
114			should be protected by Portage during updates.
115			</ti>
116			</tr>
117			<tr>
118			<ti>CONFIG_PROTECT_MASK</ti>
119			<ti>
120			This variable contains a <e>space</e>-delimited list of directories which
121			should not be protected by Portage during updates.
122			</ti>
123			</tr>
124			</table>
125
126			<p>
127			Below you will find an example definition of all these variables:
128			</p>
129
130			<pre caption="Example definitions">
131			PATH="/bin:/usr/bin:/usr/local/bin:/opt/bin:/usr/games/bin"
132			ROOTPATH="/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin"
133			LDPATH="/lib:/usr/lib:/usr/local/lib:/usr/lib/gcc-lib/i686-pc-linux-gnu/3.2.3"
134			MANPATH="/usr/share/man:/usr/local/share/man"
135			INFODIR="/usr/share/info:/usr/local/share/info"
136			PAGER="/usr/bin/less"
137			EDITOR="/usr/bin/vim"
138	swift	1.4	KDEDIRS="/usr"
139			CLASSPATH="/opt/blackdown-jre-1.4.1/lib/rt.jar:."
140			CONFIG_PROTECT="/usr/X11R6/lib/X11/xkb /opt/tomcat/conf \
141			/usr/kde/3.1/share/config /usr/share/texmf/tex/generic/config/ \
142			/usr/share/texmf/tex/platex/config/ /usr/share/config"
143			CONFIG_PROTECT_MASK="/etc/gconf
144	swift	1.2	</pre>
145
146	swift	1.1	</body>
147			</subsection>
148			</section>
149			<section>
150			<title>Defining Variables Globally</title>
151			<subsection>
152			<title>The /etc/env.d Directory</title>
153			<body>
154
155	swift	1.2	<p>
156			To centralise the definitions of these variables, Gentoo introduced the
157			<path>/etc/env.d</path> directory. Inside this directory you will find a number
158			of files, such as <path>00basic</path>, <path>05gcc</path>, etc. which contain
159			the variables needed by the application mentioned in their name.
160			</p>
161
162			<p>
163			For instance, when you installed <c>gcc</c>, a file called <path>05gcc</path>
164			was created by the ebuild which contains the definitions of the following
165			variables:
166			</p>
167
168	swift	1.7	<pre caption="/etc/env.d/05gcc">
169	swift	1.2	PATH="/usr/i686-pc-linux-gnu/gcc-bin/3.2"
170			ROOTPATH="/usr/i686-pc-linux-gnu/gcc-bin/3.2"
171			MANPATH="/usr/share/gcc-data/i686-pc-linux-gnu/3.2/man"
172			INFOPATH="/usr/share/gcc-data/i686-pc-linux-gnu/3.2/info"
173			CC="gcc"
174			CXX="g++"
175			LDPATH="/usr/lib/gcc-lib/i686-pc-linux-gnu/3.2.3"
176			</pre>
177
178			<p>
179			Other distributions tell you to change or add such environment variable
180			definitions in <path>/etc/profile</path> or other locations. Gentoo on the other
181			hand makes it easy for you (and for Portage) to maintain and manage the
182			environment variables without having to pay attention to the numerous files that
183			can contain environment variables.
184			</p>
185
186			<p>
187			For instance, when <c>gcc</c> is updated, the <path>/etc/env.d/05gcc</path> file
188			is updated too without requesting any user-interaction.
189			</p>
190
191			<p>
192	neysx	1.8	This not only benefits Portage, but also you, as user. Occasionally you might
193	swift	1.2	be asked to set a certain environment variable system-wide. As an example we
194	neysx	1.8	take the <c>http_proxy</c> variable. Instead of messing about with
195	swift	1.2	<path>/etc/profile</path>, you can now just create a file
196			(<path>/etc/env.d/99local</path>) and enter your definition(s) in it:
197			</p>
198
199			<pre caption="/etc/env.d/99local">
200			http_proxy="proxy.server.com:8080"
201			</pre>
202
203			<p>
204			By using the same file for all your variables, you have a quick overview on the
205			variables you have defined yourself.
206			</p>
207
208	swift	1.1	</body>
209			</subsection>
210			<subsection>
211			<title>The env-update Script</title>
212			<body>
213
214	swift	1.2	<p>
215			Several files in <path>/etc/env.d</path> define the <c>PATH</c> variable. This
216	neysx	1.8	is not a mistake: when you run <c>env-update</c>, it will append the several
217	swift	1.2	definitions before it updates the environment variables, thereby making it easy
218			for packages (or users) to add their own environment variable settings without
219			interfering with the already existing values.
220			</p>
221
222			<p>
223	neysx	1.16	The <c>env-update</c> script will append the values in the alphabetical order
224			of the <path>/etc/env.d</path> files. The file names must begin with two
225			decimal digits.
226	swift	1.2	</p>
227
228			<pre caption="Update order used by env-update">
229			00basic 99kde-env 99local
230			+-------------+----------------+-------------+
231			PATH="/bin:/usr/bin:/usr/kde/3.2/bin:/usr/local/bin"
232			</pre>
233
234			<p>
235	swift	1.12	The concatenation of variables does not always happen, only with the following
236			variables: <c>KDEDIRS</c>, <c>PATH</c>, <c>CLASSPATH</c>, <c>LDPATH</c>,
237			<c>MANPATH</c>, <c>INFODIR</c>, <c>INFOPATH</c>, <c>ROOTPATH</c>,
238			<c>CONFIG_PROTECT</c>, <c>CONFIG_PROTECT_MASK</c>, <c>PRELINK_PATH</c> and
239			<c>PRELINK_PATH_MASK</c>. For all other variables the latest defined value (in
240			alphabetical order of the files in <path>/etc/env.d</path>) is used.
241			</p>
242
243			<p>
244	swift	1.2	When you run <c>env-update</c>, the script will create all environment variables
245			and place them in <path>/etc/profile.env</path> (which is used by
246			<path>/etc/profile</path>). It will also extract the information from the
247			<c>LDPATH</c> variable and use that to create <path>/etc/ld.so.conf</path>.
248			After this, it will run <c>ldconfig</c> to recreate the
249			<path>/etc/ld.so.cache</path> file used by the dynamical linker.
250			</p>
251
252			<p>
253	swift	1.3	If you want to notice the effect of <c>env-update</c> immediately after you run
254			it, execute the following command to update your environment. Users who have
255	swift	1.2	installed Gentoo themselves will probably remember this from the installation
256			instructions:
257			</p>
258
259			<pre caption="Updating the environment">
260			# <i>env-update && source /etc/profile</i>
261			</pre>
262
263	smithj	1.13	<note>
264	smithj	1.14	The above command only updates the variables in your current terminal,
265			<e>new</e> consoles, and their children. Thus, if you are working in X11, you
266			will need to either type <c>source /etc/profile</c> in every new terminal you
267			open or restart X so that all new terminals source the new variables. If you
268			use a login manager, become root and type <c>/etc/init.d/xdm restart</c>. If
269			not, you will need to logout and log back in for X to spawn children with the
270			new variable values.
271	smithj	1.13	</note>
272
273	swift	1.1	</body>
274			</subsection>
275			</section>
276			<section>
277			<title>Defining Variables Locally</title>
278			<subsection>
279			<title>User Specific</title>
280			<body>
281
282	swift	1.2	<p>
283			You do not always want to define an environment variable globally. For instance,
284	swift	1.15	you might want to add <path>/home/my_user/bin</path> and the current working
285			directory (the directory you are in) to the <c>PATH</c> variable
286	swift	1.2	but don't want all other users on your system to have that in their <c>PATH</c>
287			too. If you want to define an environment variable locally, you should use
288			<path>~/.bashrc</path> or <path>~/.bash_profile</path>:
289			</p>
290
291			<pre caption="Extending PATH for local usage in ~/.bashrc">
292	swift	1.15	<comment>(A colon followed by no directory is treated as the current working directory)</comment>
293			PATH="${PATH}:/home/my_user/bin:"
294	swift	1.2	</pre>
295
296			<p>
297			When you relogin, your <c>PATH</c> variable will be updated.
298			</p>
299
300	swift	1.1	</body>
301			</subsection>
302			<subsection>
303			<title>Session Specific</title>
304			<body>
305	swift	1.2
306			<p>
307			Sometimes even stricter definitions are requested. You might want to be able to
308			use binaries from a temporary directory you created without using the path to
309	neysx	1.8	the binaries themselves or editing <path>~/.bashrc</path> for the short time
310	swift	1.2	you need it.
311			</p>
312
313			<p>
314			In this case, you can just define the <c>PATH</c> variable in your current
315			session by using the <c>export</c> command. As long as you don't log out, the
316			<c>PATH</c> variable will be using the temporary settings.
317			</p>
318
319			<pre caption="Defining a session-specific environment variable">
320			# <i>export PATH="${PATH}:/home/my_user/tmp/usr/bin"</i>
321			</pre>
322	swift	1.1
323			</body>
324			</subsection>
325			</section>
326			</sections>