/[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.23 - (show annotations) (download) (as text)
Fri Jun 29 15:41:54 2012 UTC (2 years ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.22: +13 -5 lines
File MIME type: application/xml
Fix bug #414801 - Add blurb about COLON_SEPARATED and SPACE_SEPARATED. Thanks to "lynx" for reporting and suggesting the fix

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.22 2007/05/19 04:13:46 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>2</version>
18 <date>2012-06-29</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>CONFIG_PROTECT</ti>
111 <ti>
112 This variable contains a <e>space</e>-delimited list of directories which
113 should be protected by Portage during updates.
114 </ti>
115 </tr>
116 <tr>
117 <ti>CONFIG_PROTECT_MASK</ti>
118 <ti>
119 This variable contains a <e>space</e>-delimited list of directories which
120 should not be protected by Portage during updates.
121 </ti>
122 </tr>
123 </table>
124
125 <p>
126 Below you will find an example definition of all these variables:
127 </p>
128
129 <pre caption="Example definitions">
130 PATH="/bin:/usr/bin:/usr/local/bin:/opt/bin:/usr/games/bin"
131 ROOTPATH="/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin"
132 LDPATH="/lib:/usr/lib:/usr/local/lib:/usr/lib/gcc-lib/i686-pc-linux-gnu/3.2.3"
133 MANPATH="/usr/share/man:/usr/local/share/man"
134 INFODIR="/usr/share/info:/usr/local/share/info"
135 PAGER="/usr/bin/less"
136 EDITOR="/usr/bin/vim"
137 KDEDIRS="/usr"
138 CONFIG_PROTECT="/usr/X11R6/lib/X11/xkb /opt/tomcat/conf \
139 /usr/kde/3.1/share/config /usr/share/texmf/tex/generic/config/ \
140 /usr/share/texmf/tex/platex/config/ /usr/share/config"
141 CONFIG_PROTECT_MASK="/etc/gconf"
142 </pre>
143
144 </body>
145 </subsection>
146 </section>
147 <section>
148 <title>Defining Variables Globally</title>
149 <subsection>
150 <title>The /etc/env.d Directory</title>
151 <body>
152
153 <p>
154 To centralise the definitions of these variables, Gentoo introduced the
155 <path>/etc/env.d</path> directory. Inside this directory you will find a number
156 of files, such as <path>00basic</path>, <path>05gcc</path>, etc. which contain
157 the variables needed by the application mentioned in their name.
158 </p>
159
160 <p>
161 For instance, when you installed <c>gcc</c>, a file called <path>05gcc</path>
162 was created by the ebuild which contains the definitions of the following
163 variables:
164 </p>
165
166 <pre caption="/etc/env.d/05gcc">
167 PATH="/usr/i686-pc-linux-gnu/gcc-bin/3.2"
168 ROOTPATH="/usr/i686-pc-linux-gnu/gcc-bin/3.2"
169 MANPATH="/usr/share/gcc-data/i686-pc-linux-gnu/3.2/man"
170 INFOPATH="/usr/share/gcc-data/i686-pc-linux-gnu/3.2/info"
171 CC="gcc"
172 CXX="g++"
173 LDPATH="/usr/lib/gcc-lib/i686-pc-linux-gnu/3.2.3"
174 </pre>
175
176 <p>
177 Other distributions tell you to change or add such environment variable
178 definitions in <path>/etc/profile</path> or other locations. Gentoo on the other
179 hand makes it easy for you (and for Portage) to maintain and manage the
180 environment variables without having to pay attention to the numerous files that
181 can contain environment variables.
182 </p>
183
184 <p>
185 For instance, when <c>gcc</c> is updated, the <path>/etc/env.d/05gcc</path> file
186 is updated too without requesting any user-interaction.
187 </p>
188
189 <p>
190 This not only benefits Portage, but also you, as user. Occasionally you might
191 be asked to set a certain environment variable system-wide. As an example we
192 take the <c>http_proxy</c> variable. Instead of messing about with
193 <path>/etc/profile</path>, you can now just create a file
194 (<path>/etc/env.d/99local</path>) and enter your definition(s) in it:
195 </p>
196
197 <pre caption="/etc/env.d/99local">
198 http_proxy="proxy.server.com:8080"
199 </pre>
200
201 <p>
202 By using the same file for all your variables, you have a quick overview on the
203 variables you have defined yourself.
204 </p>
205
206 </body>
207 </subsection>
208 <subsection>
209 <title>The env-update Script</title>
210 <body>
211
212 <p>
213 Several files in <path>/etc/env.d</path> define the <c>PATH</c> variable. This
214 is not a mistake: when you run <c>env-update</c>, it will append the several
215 definitions before it updates the environment variables, thereby making it easy
216 for packages (or users) to add their own environment variable settings without
217 interfering with the already existing values.
218 </p>
219
220 <p>
221 The <c>env-update</c> script will append the values in the alphabetical order
222 of the <path>/etc/env.d</path> files. The file names must begin with two
223 decimal digits.
224 </p>
225
226 <pre caption="Update order used by env-update">
227 00basic 99kde-env 99local
228 +-------------+----------------+-------------+
229 PATH="/bin:/usr/bin:/usr/kde/3.2/bin:/usr/local/bin"
230 </pre>
231
232 <p>
233 The concatenation of variables does not always happen, only with the following
234 variables: <c>ADA_INCLUDE_PATH</c>, <c>ADA_OBJECTS_PATH</c>, <c>CLASSPATH</c>,
235 <c>KDEDIRS</c>, <c>PATH</c>, <c>LDPATH</c>, <c>MANPATH</c>,
236 <c>INFODIR</c>, <c>INFOPATH</c>, <c>ROOTPATH</c>, <c>CONFIG_PROTECT</c>,
237 <c>CONFIG_PROTECT_MASK</c>, <c>PRELINK_PATH</c>, <c>PRELINK_PATH_MASK</c>,
238 <c>PKG_CONFIG_PATH</c> and <c>PYTHONPATH</c>.
239 For all other variables the latest defined value (in alphabetical order of the
240 files in <path>/etc/env.d</path>) is used.
241 </p>
242
243 <p>
244 You can add more variables into this list of concatenate-variables by adding the
245 variable name to either <c>COLON_SEPARATED</c> or <c>SPACE_SEPARATED</c>
246 variables (also inside an env.d file).
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 <impo>
280 You cannot use shell variables when defining other variables. This means things
281 like <c>FOO="$BAR"</c> (where <c>$BAR</c> is another variable) are forbidden.
282 </impo>
283
284 </body>
285 </subsection>
286 </section>
287 <section>
288 <title>Defining Variables Locally</title>
289 <subsection>
290 <title>User Specific</title>
291 <body>
292
293 <p>
294 You do not always want to define an environment variable globally. For instance,
295 you might want to add <path>/home/my_user/bin</path> and the current working
296 directory (the directory you are in) to the <c>PATH</c> variable
297 but don't want all other users on your system to have that in their <c>PATH</c>
298 too. If you want to define an environment variable locally, you should use
299 <path>~/.bashrc</path> or <path>~/.bash_profile</path>:
300 </p>
301
302 <pre caption="Extending PATH for local usage in ~/.bashrc">
303 <comment>(A colon followed by no directory is treated as the current working directory)</comment>
304 PATH="${PATH}:/home/my_user/bin:"
305 </pre>
306
307 <p>
308 When you relogin, your <c>PATH</c> variable will be updated.
309 </p>
310
311 </body>
312 </subsection>
313 <subsection>
314 <title>Session Specific</title>
315 <body>
316
317 <p>
318 Sometimes even stricter definitions are requested. You might want to be able to
319 use binaries from a temporary directory you created without using the path to
320 the binaries themselves or editing <path>~/.bashrc</path> for the short time
321 you need it.
322 </p>
323
324 <p>
325 In this case, you can just define the <c>PATH</c> variable in your current
326 session by using the <c>export</c> command. As long as you don't log out, the
327 <c>PATH</c> variable will be using the temporary settings.
328 </p>
329
330 <pre caption="Defining a session-specific environment variable">
331 # <i>export PATH="${PATH}:/home/my_user/tmp/usr/bin"</i>
332 </pre>
333
334 </body>
335 </subsection>
336 </section>
337 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20