/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-variables.xml
Gentoo

Diff of /xml/htdocs/doc/en/handbook/hb-working-variables.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

  ViewVC Help
Powered by ViewVC 1.1.20