<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Installation</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="sam.requirements.html">Requirements</a></div>
<div class="next" style="text-align: right; float: right;"><a href="sam.configuration.html">Runtime Configuration</a></div>
<div class="up"><a href="sam.setup.html">Installing/Configuring</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="sam.installation" class="section">
<h2 class="title">Installation</h2>
<p class="para">
Information for installing this PECL extension may be
found in the manual chapter titled <a href="install.pecl.html" class="link">Installation
of PECL extensions</a>. Additional information such as new releases,
downloads, source files, maintainer information, and a CHANGELOG, can be
located here:
<a href="http://pecl.php.net/package/sam" class="link external">» http://pecl.php.net/package/sam</a>.
</p>
<p class="para">
The SAM framework and MQTT support can be built and used without any other prerequisites.
Support for protocols other than MQTT is provided via a set of libraries and some client
side code referred to as XMS.
</p>
<p class="para">
If you only intend to use the built-in MQTT support then you can build and
configure SAM as an extension or simply refer to
<var class="filename">php_sam.php</var> with a <span class="function"><a href="function.require.html" class="function">require</a></span> or
<span class="function"><a href="function.require-once.html" class="function">require_once</a></span> clause in your PHP script. In this case
you need only install the code without building the extension using the pear
installer:
<div class="example-contents screen">
<div class="cdata"><pre>
pecl install -B SAM
</pre></div>
</div>
</p>
<div class="section" id="sam.installation.linux">
<h2 class="title">Linux installation steps</h2>
<p class="para">
The sam extension is supplied as a PECL module, which
you should be able to download and install in one step as follows:
<div class="example-contents screen">
<div class="cdata"><pre>
pecl install sam
</pre></div>
</div>
(Depending on your php environment, you will probably need to be root
to do this.)
</p>
<p class="para">
Make sure that the module is loaded by PHP, by adding following line
to <var class="filename">php.ini</var>:
<div class="example-contents screen">
<div class="cdata"><pre>
extension=sam.so
</pre></div>
</div>
If you intend to use the XMS support to access the IBM Messaging and Queuing family
you must also enable the SAM XMS extension.
<div class="example-contents screen">
<div class="cdata"><pre>
extension=sam_xms.so
</pre></div>
</div>
</p>
<p class="para">
If you cannot use the PEAR installer, you can download the extension
and build it manually:
<div class="example-contents screen">
<div class="cdata"><pre>
pear download sam #downloads sam-<version>.tgz
tar -xzf sam-<version>.tgz
cd sam-<version>
phpize
./configure
make
make install #you may need to be root for this step
</pre></div>
</div>
</p>
<p class="para">
To work with the very latest source, you'll need to extract it from
SVN and build manually as above.
</p>
</div>
<div class="section" id="sam.installation.windows">
<h2 class="title">Windows installation steps</h2>
<p class="para">
You will probably need to build the sam extension for Windows as there
are only a limited range of pre-built binaries available from the SAM website.
The extension can be built using the standard Windows extension build procedures.
</p>
<p class="para">
You will need the PHP source tree for the version of PHP you wish to
build the SAM extension against which you can obtain from php.net.
This should be unpacked into a working directory of your choice.
</p>
<p class="para">
You will also need the libraries and headers used by PHP extensions
available from http://www.php.net/extra/win32build.zip and this
should be unzipped so that is in your working directory.
</p>
<p class="para">
You should have something like:
<div class="example-contents screen">
<div class="cdata"><pre>
c:\php-build\-
|
|---php-5.0.5--|---build
| |---ext
| |--- ...
|
|---win32build--|---bin
|---include
|---lib
</pre></div>
</div>
</p>
<p class="para">
You will need a compiler such as the free version of Visual Studio C++
Express from the Microsoft web site. Also you need the Microsoft
<em>SDK Microsoft Windows Platform</em> which again can be
downloaded from the Microsoft web site.
</p>
<p class="para">
Obtain the SAM extension source using pear (pecl download sam) or by using
SVN and copy the files to a new "sam" directory under the "ext" directory
in your PHP source tree.
</p>
<p class="para">
To build the extension open a build environment window by going to the
start <div class="example-contents screen">menu->all programs->microsoft platform SDK for windows-><br />
open build environment window->windows 200 build environment-><br />
set windows 2000 build environment (retail)</div>
</p>
<p class="para">
This should open a command prompt with all the environment variables
set up to access the platform SDK etc. You then need to set the
environment variables for Visual Studio by issuing the command
<strong class="command">vcvars32.bat</strong> in the window.
</p>
<p class="para">
Change directory to your working directory e.g.
cd <var class="filename">c:\php-build</var>. Then
make sure the win32build tools are accessible by adding them to the
PATH environment variable:
<div class="example-contents screen">
<div class="cdata"><pre>
set PATH=..\win32build\bin;%PATH%
</pre></div>
</div>
</p>
<p class="para">
Run the <strong class="command">buildconf.bat</strong> command. This should rebuild the
<var class="filename">configure.js</var> file.
</p>
<p class="para">
Run the <strong class="command">cscript</strong> command with the appropriate options. To build just the
SAM extension framework and MQTT support use:
<div class="example-contents screen">
<div class="cdata"><pre>
cscript /nologo configure.js --with-sam
</pre></div>
</div>
To build the SAM framework and the XMS support use:
<div class="example-contents screen">
<div class="cdata"><pre>
cscript /nologo configure.js --with-sam --with-sam_xms="c:\program files\ibm\xms"
</pre></div>
</div>
</p>
<p class="para">
The additional parameter passed for sam_xms is the installation path to the
XMS libraries and runtime that were installed as described under prerequisites
at the top of this page.
</p>
<p class="para">
You can specify whatever other <strong class="command">cscript</strong> parameters you require to
include or exclude items from the php build or select options.
</p>
<p class="para">
Assuming all has gone well so far you can now finally run a make for the SAM framework!
<div class="example-contents screen">
<div class="cdata"><pre>
nmake php_sam.dll
</pre></div>
</div>
Also if you are using the XMS support you must make the sam_xms extensions:
<div class="example-contents screen">
<div class="cdata"><pre>
nmake php_sam_xms.dll
</pre></div>
</div>
</p>
<p class="para">
If you have used Visual Studio 2005 to build the DLLs please see below for additional steps that
must be carried out before proceeding further.
</p>
<p class="para">
The DLLs created (<var class="filename">php_sam.dll</var> and optionally
<var class="filename">php_sam_xms.dll</var>) can now be copied to the subdirectory
appropriate for your PHP set-up. Make sure that the module(s) are loaded by
PHP, by adding following line to <var class="filename">php.ini</var>:
<div class="example-contents screen">
<div class="cdata"><pre>
extension=php_sam.dll
</pre></div>
</div>
If you intend to use the XMS support to access the IBM Messaging and Queuing family
you must also enable the SAM XMS extension.
<div class="example-contents screen">
<div class="cdata"><pre>
extension=php_sam_xms.dll
</pre></div>
</div>
</p>
</div>
<div class="section" id="sam.installation.vs2005">
<h2 class="title">Additional steps for Visual Studio 2005</h2>
<p class="para">
If you build the SAM extension with the Microsoft Visual Studio 2005
compiler and tools you need to perform an additional step in the build
process to ensure the <var class="filename">php_sam.dll</var> is able to link
with the C runtime libraries at runtime. This step includes the
dependancy manifest into the DLL. Switch to the directory where the
<var class="filename">php_sam.dll</var> has been generated (usually
Release_TS or Debug_TS below the php source directory) and issue the
following magic incantation:
<div class="example-contents screen">
<div class="cdata"><pre>
mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2
</pre></div>
</div>
If you are using the XMS capabilities you will need to do the same with the
SAM XMS DLL:
<div class="example-contents screen">
<div class="cdata"><pre>
mt.exe -manifest php_sam_xms.dll.manifest -outputresource:php_sam_xms.dll;2
</pre></div>
</div>
</p>
<p class="para">
If you build the SAM extension using the compiler and libraries from
Microsoft Visual Studio 2005 you will also need to ensure that the
runtime components are installed on the system on which you intend to
use SAM. This can be accomplished by installing Visual Studio 2005 or
by using the freely distributable
<a href="http://www.microsoft.com/downloads/details.aspx?familyid=32BC1BEE-A3F9-4C13-9C99-220B62A191EE&displaylang=en" class="link external">» runtime package</a>.
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="sam.requirements.html">Requirements</a></div>
<div class="next" style="text-align: right; float: right;"><a href="sam.configuration.html">Runtime Configuration</a></div>
<div class="up"><a href="sam.setup.html">Installing/Configuring</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
