/[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.21 - (show annotations) (download) (as text)
Mon Apr 2 09:41:49 2007 UTC (8 years, 4 months ago) by neysx
Branch: MAIN
Changes since 1.20: +8 -16 lines
File MIME type: application/xml
#173101 Removed CLASSPATH

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.20 2006/10/28 09:17:55 neysx 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.15</version>
18 <date>2007-04-02</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>KDEDIRS</c>, <c>PATH</c>, <c>LDPATH</c>, <c>MANPATH</c>,
235 <c>INFODIR</c>, <c>INFOPATH</c>, <c>ROOTPATH</c>, <c>CONFIG_PROTECT</c>,
236 <c>CONFIG_PROTECT_MASK</c>, <c>PRELINK_PATH</c> and <c>PRELINK_PATH_MASK</c>.
237 For all other variables the latest defined value (in alphabetical order of the
238 files in <path>/etc/env.d</path>) is used.
239 </p>
240
241 <p>
242 When you run <c>env-update</c>, the script will create all environment variables
243 and place them in <path>/etc/profile.env</path> (which is used by
244 <path>/etc/profile</path>). It will also extract the information from the
245 <c>LDPATH</c> variable and use that to create <path>/etc/ld.so.conf</path>.
246 After this, it will run <c>ldconfig</c> to recreate the
247 <path>/etc/ld.so.cache</path> file used by the dynamical linker.
248 </p>
249
250 <p>
251 If you want to notice the effect of <c>env-update</c> immediately after you run
252 it, execute the following command to update your environment. Users who have
253 installed Gentoo themselves will probably remember this from the installation
254 instructions:
255 </p>
256
257 <pre caption="Updating the environment">
258 # <i>env-update &amp;&amp; source /etc/profile</i>
259 </pre>
260
261 <note>
262 The above command only updates the variables in your current terminal,
263 <e>new</e> consoles, and their children. Thus, if you are working in X11, you
264 will need to either type <c>source /etc/profile</c> in every new terminal you
265 open or restart X so that all new terminals source the new variables. If you
266 use a login manager, become root and type <c>/etc/init.d/xdm restart</c>. If
267 not, you will need to logout and log back in for X to spawn children with the
268 new variable values.
269 </note>
270
271 </body>
272 </subsection>
273 </section>
274 <section>
275 <title>Defining Variables Locally</title>
276 <subsection>
277 <title>User Specific</title>
278 <body>
279
280 <p>
281 You do not always want to define an environment variable globally. For instance,
282 you might want to add <path>/home/my_user/bin</path> and the current working
283 directory (the directory you are in) to the <c>PATH</c> variable
284 but don't want all other users on your system to have that in their <c>PATH</c>
285 too. If you want to define an environment variable locally, you should use
286 <path>~/.bashrc</path> or <path>~/.bash_profile</path>:
287 </p>
288
289 <pre caption="Extending PATH for local usage in ~/.bashrc">
290 <comment>(A colon followed by no directory is treated as the current working directory)</comment>
291 PATH="${PATH}:/home/my_user/bin:"
292 </pre>
293
294 <p>
295 When you relogin, your <c>PATH</c> variable will be updated.
296 </p>
297
298 </body>
299 </subsection>
300 <subsection>
301 <title>Session Specific</title>
302 <body>
303
304 <p>
305 Sometimes even stricter definitions are requested. You might want to be able to
306 use binaries from a temporary directory you created without using the path to
307 the binaries themselves or editing <path>~/.bashrc</path> for the short time
308 you need it.
309 </p>
310
311 <p>
312 In this case, you can just define the <c>PATH</c> variable in your current
313 session by using the <c>export</c> command. As long as you don't log out, the
314 <c>PATH</c> variable will be using the temporary settings.
315 </p>
316
317 <pre caption="Defining a session-specific environment variable">
318 # <i>export PATH="${PATH}:/home/my_user/tmp/usr/bin"</i>
319 </pre>
320
321 </body>
322 </subsection>
323 </section>
324 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20