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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.20 - (show annotations) (download) (as text)
Sat Oct 28 09:17:55 2006 UTC (7 years, 10 months ago) by neysx
Branch: MAIN
Changes since 1.19: +7 -1 lines
File MIME type: application/xml
Moved chapter abstracts into shared chapters
No content change, hence no bump

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

  ViewVC Help
Powered by ViewVC 1.1.20