common/src/docs/cn/src/documentation/content/xdocs/native_libraries.xml - hadoop - Git at Google

 <?xml version="1.0" encoding="utf-8"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->

 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">

 <document>

   <header>
     <title>Hadoop本地库</title>
   </header>

   <body>

     <section>
       <title>目的</title>

       <p>
      鉴于性能问题以及某些Java类库的缺失，对于某些组件，Hadoop提供了自己的本地实现。
 	这些组件保存在Hadoop的一个独立的动态链接的库里。这个库在*nix平台上叫<em>libhadoop.so</em>. 本文主要介绍本地库的使用方法以及如何构建本地库。
 </p>
     </section>

     <section>
       <title>组件</title>

       <p>Hadoop现在已经有以下
       <a href="ext:api/org/apache/hadoop/io/compress/compressioncodec">
       compression codecs</a>本地组件：</p>
       <ul>
         <li><a href="ext:zlib">zlib</a></li>
         <li><a href="ext:gzip">gzip</a></li>
         <li><a href="ext:lzo">lzo</a></li>
       </ul>

       <p>在以上组件中，lzo和gzip压缩编解码器必须使用hadoop本地库才能运行。
       </p>
     </section>

     <section>
       <title>使用方法</title>

       <p>hadoop本地库的用法很简单：</p>

       <ul>
         <li>
           看一下
 	<a href="#支持的平台">支持的平台</a>.
         </li>
         <li>
            <a href="ext:releases/download">下载</a> 预构建的32位i386架构的Linux本地hadoop库（可以在hadoop发行版的<code>lib/native</code>目录下找到）或者自己
           <a href="#构建Hadoop本地库">构建</a> 这些库。
         </li>
         <li>
           确保你的平台已经安装了<strong>zlib-1.2</strong>以上版本或者<strong>lzo2.0</strong>以上版本的软件包或者两者均已安装（根据你的需要）。
         </li>
       </ul>

       <p><code>bin/hadoop</code> 脚本通过系统属性
       <em>-Djava.library.path=&lt;path&gt;</em>来确认hadoop本地库是否包含在库路径里。</p>

       <p>检查hadoop日志文件可以查看hadoop库是否正常，正常情况下会看到：</p>

       <p>
         <code>
           DEBUG util.NativeCodeLoader - Trying to load the custom-built
           native-hadoop library...
         </code><br/>
         <code>
           INFO  util.NativeCodeLoader - Loaded the native-hadoop library
         </code>
       </p>

       <p>如果出错，会看到：</p>
       <p>
         <code>
           INFO util.NativeCodeLoader - Unable to load native-hadoop library for
           your platform... using builtin-java classes where applicable
         </code>
       </p>
     </section>

     <section>
       <title>支持的平台</title>

       <p>Hadoop本地库只支持*nix平台，已经广泛使用在GNU/Linux平台上，但是不支持
       <a href="ext:cygwin">Cygwin</a>
       和 <a href="ext:osx">Mac OS X</a>。
       </p>

       <p>已经测试过的GNU/Linux发行版本：</p>
       <ul>
         <li>
           <a href="http://www.redhat.com/rhel/">RHEL4</a>/<a href="http://fedora.redhat.com/">Fedora</a>
         </li>
         <li><a href="http://www.ubuntu.com/">Ubuntu</a></li>
         <li><a href="http://www.gentoo.org/">Gentoo</a></li>
       </ul>

       <p>在上述平台上，32/64位Hadoop本地库分别能和32/64位的jvm一起正常运行。
       </p>
     </section>

     <section>
       <title>构建Hadoop本地库</title>

       <p>Hadoop本地库使用
       <a href="http://en.wikipedia.org/wiki/ANSI_C">ANSI C</a> 编写，使用GNU autotools工具链 (autoconf, autoheader, automake, autoscan, libtool)构建。也就是说构建hadoop库的平台需要有标准C的编译器和GNU autotools工具链。请参看
       <a href="#支持的平台">支持的平台</a>。</p>

       <p>你的目标平台上可能会需要的软件包：
       </p>
       <ul>
         <li>
           C 编译器 (e.g. <a href="http://gcc.gnu.org/">GNU C Compiler</a>)
         </li>
         <li>
           GNU Autools 工具链:
           <a href="http://www.gnu.org/software/autoconf/">autoconf</a>,
           <a href="http://www.gnu.org/software/automake/">automake</a>,
           <a href="http://www.gnu.org/software/libtool/">libtool</a>
         </li>
         <li>
           zlib开发包 (stable version >= 1.2.0)
         </li>
         <li>
           lzo开发包 (stable version >= 2.0)
         </li>
       </ul>

       <p>如果已经满足了上述先决条件，可以使用<code>build.xml</code>
       文件，并把其中的<code>compile.native</code>置为
       <code>true</code>，这样就可以生成hadoop本地库：</p>

       <p><code>$ ant -Dcompile.native=true &lt;target&gt;</code></p>

       <p>因为不是所有用户都需要Hadoop本地库，所以默认情况下hadoop不生成该库。
       </p>

       <p>你可以在下面的路径查看新生成的hadoop本地库：</p>

       <p><code>$ build/native/&lt;platform&gt;/lib</code></p>

       <p>其中&lt;platform&gt;是下列系统属性的组合
       <code>${os.name}-${os.arch}-${sun.arch.data.model}</code>；例如
       Linux-i386-32。</p>

       <section>
         <title>注意</title>

         <ul>
           <li>
             在生成hadoop本地库的目标平台上<strong>必须</strong> 安装了zlib和lzo开发包；但是如果你只希望使用其中一个的话，在部署时，安装其中任何一个都是足够的。
           </li>
           <li>
 		  在目标平台上生成以及部署hadoop本地库时，都需要根据32/64位jvm选取对应的32/64位zlib/lzo软件包。
           </li>
         </ul>
       </section>
     </section>
 <!--DCCOMMENT:diff begin-->
     <section>
       <title> 使用DistributedCache 加载本地库</title>
       <p>用户可以通过
       <a href="mapred_tutorial.html#DistributedCache">DistributedCache</a>
       加载本地共享库，并<em>分发</em>和建立库文件的<em>符号链接</em>。
       </p>
       <!--DCCOMMENT:
       for <em>distributing</em> and <em>symlinking</em> the library files</p>
       -->
       <p>这个例子描述了如何分发库文件并在从map/reduce任务中装载库文件。
       </p>
       <ol>
       <li>首先拷贝库文件到HDFS。<br/>
       <code>bin/hadoop fs -copyFromLocal mylib.so.1 /libraries/mylib.so.1</code>
       </li>
       <li>启动作业时包含以下代码：<br/>
       <code> DistributedCache.createSymlink(conf); </code> <br/>
       <code> DistributedCache.addCacheFile("hdfs://host:port/libraries/mylib.so.1#mylib.so", conf);
       </code>
       </li>
       <li>map/reduce任务中包含以下代码：<br/>
       <code> System.loadLibrary("mylib.so"); </code>
       </li>
       </ol>
     </section>
   </body>

 </document>
 <!--DCCOMMENT:diff end
      </section>
 +    <section>
 +      <title> Loading native libraries through DistributedCache </title>
 +      <p>User can load native shared libraries through
 +      <a href="mapred_tutorial.html#DistributedCache">DistributedCache</a>
 +      for <em>distributing</em> and <em>symlinking</em> the library files</p>
 +
 +      <p>Here is an example, describing how to distribute the library and
 +      load it from map/reduce task. </p>
 +      <ol>
 +      <li> First copy the library to the HDFS. <br/>
 +      <code>bin/hadoop fs -copyFromLocal mylib.so.1 /libraries/mylib.so.1</code>
 +      </li>
 +      <li> The job launching program should contain the following: <br/>
 +      <code> DistributedCache.createSymlink(conf); </code> <br/>
 +      <code> DistributedCache.addCacheFile("hdfs://host:port/libraries/mylib.so.1#mylib.so", conf);
 +      </code>
 +      </li>
 +      <li> The map/reduce task can contain: <br/>
 +      <code> System.loadLibrary("mylib.so"); </code>
 +      </li>
 +      </ol>
 +    </section>
    </body>

 -->
	<?xml version="1.0" encoding="utf-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">

	<document>

	<header>
	<title>Hadoop本地库</title>
	</header>

	<body>

	<section>
	<title>目的</title>

	<p>
	鉴于性能问题以及某些Java类库的缺失，对于某些组件，Hadoop提供了自己的本地实现。
	这些组件保存在Hadoop的一个独立的动态链接的库里。这个库在*nix平台上叫<em>libhadoop.so</em>. 本文主要介绍本地库的使用方法以及如何构建本地库。
	</p>
	</section>

	<section>
	<title>组件</title>

	<p>Hadoop现在已经有以下
	<a href="ext:api/org/apache/hadoop/io/compress/compressioncodec">
	compression codecs</a>本地组件：</p>
	<ul>
	<li><a href="ext:zlib">zlib</a></li>
	<li><a href="ext:gzip">gzip</a></li>
	<li><a href="ext:lzo">lzo</a></li>
	</ul>

	<p>在以上组件中，lzo和gzip压缩编解码器必须使用hadoop本地库才能运行。
	</p>
	</section>

	<section>
	<title>使用方法</title>

	<p>hadoop本地库的用法很简单：</p>

	<ul>
	<li>
	看一下
	<a href="#支持的平台">支持的平台</a>.
	</li>
	<li>
	<a href="ext:releases/download">下载</a> 预构建的32位i386架构的Linux本地hadoop库（可以在hadoop发行版的<code>lib/native</code>目录下找到）或者自己
	<a href="#构建Hadoop本地库">构建</a> 这些库。
	</li>
	<li>
	确保你的平台已经安装了<strong>zlib-1.2</strong>以上版本或者<strong>lzo2.0</strong>以上版本的软件包或者两者均已安装（根据你的需要）。
	</li>
	</ul>

	<p><code>bin/hadoop</code> 脚本通过系统属性
	<em>-Djava.library.path=<path></em>来确认hadoop本地库是否包含在库路径里。</p>

	<p>检查hadoop日志文件可以查看hadoop库是否正常，正常情况下会看到：</p>

	<p>
	<code>
	DEBUG util.NativeCodeLoader - Trying to load the custom-built
	native-hadoop library...
	</code><br/>
	<code>
	INFO util.NativeCodeLoader - Loaded the native-hadoop library
	</code>
	</p>

	<p>如果出错，会看到：</p>
	<p>
	<code>
	INFO util.NativeCodeLoader - Unable to load native-hadoop library for
	your platform... using builtin-java classes where applicable
	</code>
	</p>
	</section>

	<section>
	<title>支持的平台</title>

	<p>Hadoop本地库只支持*nix平台，已经广泛使用在GNU/Linux平台上，但是不支持
	<a href="ext:cygwin">Cygwin</a>
	和 <a href="ext:osx">Mac OS X</a>。
	</p>

	<p>已经测试过的GNU/Linux发行版本：</p>
	<ul>
	<li>
	<a href="http://www.redhat.com/rhel/">RHEL4</a>/<a href="http://fedora.redhat.com/">Fedora</a>
	</li>
	<li><a href="http://www.ubuntu.com/">Ubuntu</a></li>
	<li><a href="http://www.gentoo.org/">Gentoo</a></li>
	</ul>

	<p>在上述平台上，32/64位Hadoop本地库分别能和32/64位的jvm一起正常运行。
	</p>
	</section>

	<section>
	<title>构建Hadoop本地库</title>

	<p>Hadoop本地库使用
	<a href="http://en.wikipedia.org/wiki/ANSI_C">ANSI C</a> 编写，使用GNU autotools工具链 (autoconf, autoheader, automake, autoscan, libtool)构建。也就是说构建hadoop库的平台需要有标准C的编译器和GNU autotools工具链。请参看
	<a href="#支持的平台">支持的平台</a>。</p>

	<p>你的目标平台上可能会需要的软件包：
	</p>
	<ul>
	<li>
	C 编译器 (e.g. <a href="http://gcc.gnu.org/">GNU C Compiler</a>)
	</li>
	<li>
	GNU Autools 工具链:
	<a href="http://www.gnu.org/software/autoconf/">autoconf</a>,
	<a href="http://www.gnu.org/software/automake/">automake</a>,
	<a href="http://www.gnu.org/software/libtool/">libtool</a>
	</li>
	<li>
	zlib开发包 (stable version >= 1.2.0)
	</li>
	<li>
	lzo开发包 (stable version >= 2.0)
	</li>
	</ul>

	<p>如果已经满足了上述先决条件，可以使用<code>build.xml</code>
	文件，并把其中的<code>compile.native</code>置为
	<code>true</code>，这样就可以生成hadoop本地库：</p>

	<p><code>$ ant -Dcompile.native=true <target></code></p>

	<p>因为不是所有用户都需要Hadoop本地库，所以默认情况下hadoop不生成该库。
	</p>

	<p>你可以在下面的路径查看新生成的hadoop本地库：</p>

	<p><code>$ build/native/<platform>/lib</code></p>

	<p>其中<platform>是下列系统属性的组合
	<code>${os.name}-${os.arch}-${sun.arch.data.model}</code>；例如
	Linux-i386-32。</p>

	<section>
	<title>注意</title>

	<ul>
	<li>
	在生成hadoop本地库的目标平台上<strong>必须</strong> 安装了zlib和lzo开发包；但是如果你只希望使用其中一个的话，在部署时，安装其中任何一个都是足够的。
	</li>
	<li>
	在目标平台上生成以及部署hadoop本地库时，都需要根据32/64位jvm选取对应的32/64位zlib/lzo软件包。
	</li>
	</ul>
	</section>
	</section>
	<!--DCCOMMENT:diff begin-->
	<section>
	<title> 使用DistributedCache 加载本地库</title>
	<p>用户可以通过
	<a href="mapred_tutorial.html#DistributedCache">DistributedCache</a>
	加载本地共享库，并<em>分发</em>和建立库文件的<em>符号链接</em>。
	</p>
	<!--DCCOMMENT:
	for <em>distributing</em> and <em>symlinking</em> the library files</p>
	-->
	<p>这个例子描述了如何分发库文件并在从map/reduce任务中装载库文件。
	</p>
	<ol>
	<li>首先拷贝库文件到HDFS。<br/>
	<code>bin/hadoop fs -copyFromLocal mylib.so.1 /libraries/mylib.so.1</code>
	</li>
	<li>启动作业时包含以下代码：<br/>
	<code> DistributedCache.createSymlink(conf); </code> <br/>
	<code> DistributedCache.addCacheFile("hdfs://host:port/libraries/mylib.so.1#mylib.so", conf);
	</code>
	</li>
	<li>map/reduce任务中包含以下代码：<br/>
	<code> System.loadLibrary("mylib.so"); </code>
	</li>
	</ol>
	</section>
	</body>

	</document>
	<!--DCCOMMENT:diff end
	</section>
	+ <section>
	+ <title> Loading native libraries through DistributedCache </title>
	+ <p>User can load native shared libraries through
	+ <a href="mapred_tutorial.html#DistributedCache">DistributedCache</a>
	+ for <em>distributing</em> and <em>symlinking</em> the library files</p>
	+
	+ <p>Here is an example, describing how to distribute the library and
	+ load it from map/reduce task. </p>
	+ <ol>
	+ <li> First copy the library to the HDFS. <br/>
	+ <code>bin/hadoop fs -copyFromLocal mylib.so.1 /libraries/mylib.so.1</code>
	+ </li>
	+ <li> The job launching program should contain the following: <br/>
	+ <code> DistributedCache.createSymlink(conf); </code> <br/>
	+ <code> DistributedCache.addCacheFile("hdfs://host:port/libraries/mylib.so.1#mylib.so", conf);
	+ </code>
	+ </li>
	+ <li> The map/reduce task can contain: <br/>
	+ <code> System.loadLibrary("mylib.so"); </code>
	+ </li>
	+ </ol>
	+ </section>
	</body>

	-->