|
|
| (9 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | <b><big>RPM User Manual</big></b><br><b>Adempiere RPM Packager</b><br>by <span class="firstname">Stefan</span> <span class="surname">Christians</span><br>2011-08-02
| + | #REDIRECT [[RPM]] |
| − | | + | |
| − | <small><i>This program is part of Adempiere ERP Bazaar<br>http://www.adempiere.org
| + | |
| − | | + | |
| − | Copyright © Stefan Christians
| + | |
| − | <br>Copyright © Contributors
| + | |
| − | | + | |
| − | This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.<br>This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.<br>You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
| + | |
| − | | + | |
| − | Contributors: <span class="personname"><span class="firstname">Stefan</span> <span class="surname">Christians</span></span>
| + | |
| − | <br>Sponsors: K.K. Alice
| + | |
| − | | + | |
| − | Adempiere is a registered trademark of Adempiere, Inc.<br>All other company or product names are mentioned for identification purposes only, and may be trademarks of their respective owners.</i></small>
| + | |
| − | | + | |
| − | | + | |
| − | <div class="abstract" title="Packaging and Distributing Adempiere on RedHat-like Systems"><p class="title"><b>Packaging and Distributing Adempiere on RedHat-like Systems</b></p><p>
| + | |
| − | This source package includes the Spec File and tools to download, customize, compile, configure, distribute, install,
| + | |
| − | and run <span class="productname">Adempiere</span> on <span class="productname">RedHat</span>-like systems which use RPM as
| + | |
| − | their package manager.
| + | |
| − | </p></div>
| + | |
| − | ----
| + | |
| − | <div><div class="titlepage"><div><div>
| + | |
| − | =Preface=
| + | |
| − | </div></div></div><p>
| + | |
| − | The Spec File to build the <span class="productname">Adempiere</span> RPM was developed and tested on
| + | |
| − | <span class="productname">Fedora</span> <span class="productnumber">13</span>.
| + | |
| − | </p><p>
| + | |
| − | The <a class="link" href="http://fedoraproject.org/wiki/Packaging:Guidelines" target="_top">Fedora Packaging Guidelines</a>
| + | |
| − | have been followed, with some exceptions:
| + | |
| − | </p><p>
| + | |
| − | </p><div><dl>
| + | |
| − | ;Version and Release Numbering
| + | |
| − | :<p>
| + | |
| − | Version information should be in the form:
| + | |
| − | </p><pre class="programlisting">majorVersion.minorVersion-buildNumber.patchNumber[<span class="optional">.releaseTag</span>]</pre><p>
| + | |
| − | So if upstream releases its product as <code class="filename">adempiere351a</code>, it should be packaged as:
| + | |
| − | </p><pre class="programlisting">adempiere-3.5-1.X.a</pre><p>
| + | |
| − | (where 1 is the build number and X is the packager's "patch level", which is incremented on each build).
| + | |
| − | </p><p>
| + | |
| − | However, upstream maintains the build number as part of the version number, and it does not follow the
| + | |
| − | convention of 0=pre-release, 1=release, >1=post-release. For RPM's version control method, it therefore
| + | |
| − | makes more sense to use the revision in the <span class="productname">Mercurial</span> repository as build number.
| + | |
| − | </p><p>
| + | |
| − | We also want to have automatic patch-level numbering, and the build date seems most suitable for that purpose.
| + | |
| − | </p><p>
| + | |
| − | Therefore, our version numbering will have following syntax:
| + | |
| − | </p><pre class="programlisting">majorVersion.minorVersion.buildNumber-hgRevision.<em>buildDate</em>[<span class="optional">.releaseTag</span>]</pre><p>
| + | |
| − | which would result in following package names:
| + | |
| − | </p><pre class="programlisting">
| + | |
| − | adempiere331 -> adempiere-3.3.1-1943.<em>buildDate</em>
| + | |
| − | adempiere354a -> adempiere-3.5.4-5276.<em>buildDate</em>.a
| + | |
| − | adempiere360lts -> adempiere-3.6.0-6510.<em>buildDate</em>.lts
| + | |
| − | </pre><p>
| + | |
| − | </p>
| + | |
| − | ;Pre-built Binaries and Libraries
| + | |
| − | :<p>
| + | |
| − | All binaries and libraries in <span class="productname">Fedora</span> packages must be built from source code.
| + | |
| − | The source package is not allowed to contain pre-built binaries and libraries.
| + | |
| − | </p><p>
| + | |
| − | However, <span class="productname">Adempiere</span> comes with various *.jar archives containing pre-built
| + | |
| − | *.class files.
| + | |
| − | </p><p>
| + | |
| − | Some of them are simply used as tools in the build-chain and would easily be replaceable with open-source
| + | |
| − | <span class="productname">Fedora</span> libraries.
| + | |
| − | </p><p>
| + | |
| − | Others are used in the final product such as the jdbc-drivers for database connections. They would be
| + | |
| − | more difficult to replace, although it would certainly be possible.
| + | |
| − | </p><p>
| + | |
| − | Since we are going to build <span class="productname">Adempiere</span> packages for our own use and not
| + | |
| − | for distribution with <span class="productname">Fedora</span>, we will gracefully ignore this requirement
| + | |
| − | for the time being.
| + | |
| − | </p>
| + | |
| − | ;Spec File Legibility
| + | |
| − | :<p>
| + | |
| − | All efforts have been made to keep the Spec File legible, whereby priority has been given to
| + | |
| − | legibility in terms of humanly readable over being able to read and understand the algorithms.
| + | |
| − | </p><p>
| + | |
| − | Normally the user would only have to set or modify parameters at the beginning of the file
| + | |
| − | (marked <span class="quote">“<span class="quote">SETTINGS</span>”</span>), add his sources and patches to the preamble (marked
| + | |
| − | <span class="quote">“<span class="quote">your custom sources come here</span>”</span> and <span class="quote">“<span class="quote">your custom patches come here</span>”</span>),
| + | |
| − | and install or apply them in the <code class="code">%prep</code> section (marked <span class="quote">“<span class="quote">install your sources here</span>”</span> and
| + | |
| − | <span class="quote">“<span class="quote">apply your patches here</span>”</span>). Everything else should just work.
| + | |
| − | </p><p>
| + | |
| − | Many different parameters can be used in the Spec File, and commenting them all in place would
| + | |
| − | result in a very long settings section where important or conflicting parameters could
| + | |
| − | easily be overlooked. Instead, the parameters are explained with their default values in the appendix
| + | |
| − | of this manual. All parameters have sensible default values, so even if no parameters are set the
| + | |
| − | Spec File will still produce an installable and runnable package.
| + | |
| − | </p><p>
| + | |
| − | Macros used by the build and installation scripts are defined and evaluated in a section titled
| + | |
| − | <span class="quote">“<span class="quote">INITIALIZATION</span>”</span>, which comes between the settings and the preamble. Inside the scripts,
| + | |
| − | the function and contents of those macros can be understood intuitively by their names, and as most
| + | |
| − | people will not want to get into the detailed algorithms of how they were defined, the definitions
| + | |
| − | are written in a way that keeps the Spec File nice and tidy and easily readable by humans. For debugging
| + | |
| − | purposes, it is recommendable to expand those macros to multiple lines where necessary for easier
| + | |
| − | understanding of conditions, loops, etc.
| + | |
| − | </p><p>
| + | |
| − | A lot of regular expressions are used in combination with <span class="command"><strong>grep</strong></span>, <span class="command"><strong>sed</strong></span>,
| + | |
| − | and <span class="command"><strong>awk</strong></span> in the macro definitions. They are not further explained, as commenting one
| + | |
| − | line of code with twenty lines of explanation would make the Spec File difficult to read as a whole.
| + | |
| − | </p><p>
| + | |
| − | Since all sub packages use exactly the same installation scripts (behavior is tweaked for each sub package
| + | |
| − | by just setting some variables at the beginning of the scripts), rather than writing the scripts again
| + | |
| − | and again, they have been included as source files which will be dynamically expanded when the packages
| + | |
| − | are built.
| + | |
| − | </p><p>
| + | |
| − | The <code class="filename">SOURCES</code> directory easily becomes very messy when numerous source files
| + | |
| − | and patches are scattered about. For this reason, the files distributed with the Source-RPM are prefixed
| + | |
| − | with sXXX_ (for sources) and pXXX_ (for patches), where XXX corresponds to the patch or source number
| + | |
| − | in the Spec File. Users are encouraged to name their sources and patches following the same scheme,
| + | |
| − | starting with number 100.
| + | |
| − | </p>
| + | |
| − | ;Tags
| + | |
| − | :<p>
| + | |
| − | The <code class="varname">Packager</code> and <code class="varname">Vendor</code> tags are used in spite of the guideline's
| + | |
| − | recommendation not to do so. They are used for identification and documentation purposes to differentiate
| + | |
| − | between the original distribution and patched versions.
| + | |
| − | </p><p>
| + | |
| − | The <code class="varname">BuildRoot</code> tag is present for compatibility with other
| + | |
| − | <span class="productname">RedHat</span>-like systems.
| + | |
| − | </p>
| + | |
| − | ;Requirements
| + | |
| − | :<p>
| + | |
| − | <span class="productname">Adempiere</span> requires <span class="productname">Java</span> to run. As of
| + | |
| − | <span class="productname">Adempiere</span> <span class="productnumber">3.6.0</span>, <span class="productname">JDK</span>
| + | |
| − | <span class="productnumber">1.6</span> is required.
| + | |
| − | </p><p>
| + | |
| − | Actually any <span class="productname">Java</span> distribution can be used, and the original
| + | |
| − | <span class="productname">Sun Java</span> software is most tested and reliable for <span class="productname">Adempiere</span>.
| + | |
| − | But since it is not distributed as an RPM, and theoretically can be installed at any location, it is virtually
| + | |
| − | impossible to check for it as a build or target requirement.
| + | |
| − | </p><p>
| + | |
| − | Therefore the <span class="productname">openJDK</span> distribution is listed as requirement for both compiling the
| + | |
| − | source and installing the RPM on a target machine. The user is still free to use any <span class="productname">Java</span>
| + | |
| − | distribution he wants, but <span class="productname">openJDK</span> must at least be installed.
| + | |
| − | </p>
| + | |
| − | ;Documentation
| + | |
| − | :<p>
| + | |
| − | <span class="productname">Adempiere</span> mainly uses online documentation. Text files such as README
| + | |
| − | in the source code are often meaningless. However, all pdf files found in the source after compiling are
| + | |
| − | copied into the documentation folder for all sub packages, regardless in which sub package they were
| + | |
| − | found and without distinguishing whether they are for users, administrators or developers.
| + | |
| − | </p>
| + | |
| − | ;Users and Groups
| + | |
| − | :<p>
| + | |
| − | If the <code class="code">adempiere</code> user or group already exists on the target system, an attempt is made
| + | |
| − | to change the uid and gid to those defined in the Spec File, and to move the home directory to the
| + | |
| − | location defined in the Spec File.
| + | |
| − | </p></dl></div><p>
| + | |
| − | </p></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Introduction=
| + | |
| − | </div><div><div class="titlepage"><div><div>
| + | |
| − | ==Platform Independence==
| + | |
| − | </div></div></div><p>
| + | |
| − | <span class="productname">Adempiere</span> is written in <span class="productname">Java</span> and as such strives to run on
| + | |
| − | any operating system which is supported by Java. In effect it means that <span class="productname">Adempiere</span> can
| + | |
| − | run on any modern operating system such as <span class="productname">Windows</span>, <span class="productname">Mac OS X</span>,
| + | |
| − | <span class="productname">Solaris</span>, and <span class="productname">Linux</span>.
| + | |
| − | </p><p>
| + | |
| − | To install <span class="productname">Adempiere</span>, you download the binary package as zip-file from
| + | |
| − | <a class="link" href="http://sourceforge.net/projects/adempiere/files/" target="_top">sourceforge</a>, drop it somewhere
| + | |
| − | into the directory tree, unzip the file, run <span class="command"><strong>RUN_setup.sh</strong></span>, and you have
| + | |
| − | <span class="productname">Adempiere</span> installed and configured. The procedure is the same on any operating system.
| + | |
| − | </p><p>
| + | |
| − | While this platform independence is remarkable, it comes at a cost: The software can not be optimized for
| + | |
| − | any particular system. Particularly on <span class="productname">Linux</span> machines, there are several issues
| + | |
| − | which shall be examined in more detail.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Linux Issues==
| + | |
| − | </div></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===The Filesystem Hierarchy Standard===
| + | |
| − | </div></div></div><p>
| + | |
| − | <span class="productname">Linux</span> follows the Filesystem Hierarchy Standard
| + | |
| − | (<a class="link" href="http://www.pathname.com/fhs/" target="_top">FHS</a>) which defines where what kind of files
| + | |
| − | should be located.
| + | |
| − | </p><p>
| + | |
| − | According to the FHS, we would expect <span class="productname">Adempiere</span> to install its files in the
| + | |
| − | following directories:
| + | |
| − | </p><div class="informaltable"><a name="tblFHSLocations"></a><table border="0"><tr><td align="left">configuration files</td><td align="left"><code class="filename">/etc/adempiere/</code></td></tr><tr><td align="left">executable binaries</td><td align="left"><code class="filename">/usr/bin/</code></td></tr><tr><td align="left">libraries and resources</td><td align="left"><code class="filename">/usr/lib/adempiere/</code></td></tr><tr><td align="left">documentation</td><td align="left"><code class="filename">/usr/share/doc/adempiere/</code></td></tr><tr><td align="left">data and variable state files</td><td align="left"><code class="filename">/var/lib/adempiere/</code></td></tr><tr><td align="left">log files</td><td align="left"><code class="filename">/var/log</code></td></tr></table></div><p>
| + | |
| − | But instead all files are just installed in one big chunk with its own sub-directory
| + | |
| − | tree originating wherever you extracted the zip-file.
| + | |
| − | </p><p>
| + | |
| − | For such cases the FHS provides the <code class="filename">/opt</code> directory, where add-on packages may install
| + | |
| − | all static files in their own subdirectory.<sup>[[#ftn.id3050553|1]]</sup>
| + | |
| − | </p><p>
| + | |
| − | Technically, even when using the <code class="filename">/opt</code> hierarchy, configuration files should actually still
| + | |
| − | be located in <code class="filename">/etc/opt/adempiere</code>, and data and variable state files in
| + | |
| − | <code class="filename">/var/opt/adempiere</code>. Executables should be placed in <code class="filename">/opt/adempiere/bin</code>.
| + | |
| − | And a restriction exists that no files should exist outside the <code class="filename">/opt</code>, <code class="filename">/var/opt</code>,
| + | |
| − | and <code class="filename">/etc/opt</code> hierarchies (except for those which must reside in specific locations to function
| + | |
| − | properly).
| + | |
| − | </p><p>
| + | |
| − | But would strictly following the FHS standard really make sense?
| + | |
| − | </p><div><div class="titlepage"><div><div>
| + | |
| − | ====Configuration Files====
| + | |
| − | </div></div></div><p>
| + | |
| − | The rational for having all host-specific configuration files under a single directory is that
| + | |
| − | users can easily predict their location. Hardcore <span class="productname">Linux</span> users much prefer
| + | |
| − | tweaking settings in a configuration file by hand rather than being guided through a lengthy
| + | |
| − | setup program.
| + | |
| − | </p><p>
| + | |
| − | But <span class="productname">Adempiere</span> does not expect anybody to modify its settings from outside and rather
| + | |
| − | insists that <span class="command"><strong>RUN_setup.sh</strong></span> is used for that purpose. Programs under <span class="productname">Linux</span>
| + | |
| − | expect that their configurations could have been changed any time, so they adjust themselves to the configured
| + | |
| − | settings after those have been loaded and checked for sanity. <span class="productname">Adempiere</span> works the
| + | |
| − | other way round: <span class="command"><strong>RUN_setup.sh</strong></span> checks the configuration parameters for sanity,
| + | |
| − | adjusts all programs and libraries to the configured settings, and then saves those settings quasi as a
| + | |
| − | saved-state file. When the programs are started, they load their last state from the configuration file and
| + | |
| − | continue from there. Should you modify anything manually from outside of <span class="command"><strong>RUN_setup.sh</strong></span>,
| + | |
| − | things will get seriously messed up.
| + | |
| − | </p><p>
| + | |
| − | In addition, the configuration files are all located near the executables and binaries where they are being used,
| + | |
| − | which is not bad for testing and debugging.
| + | |
| − | </p><p>
| + | |
| − | Under these considerations, it probably makes sense to keep the configuration files where they are
| + | |
| − | and not to move them to <code class="filename">/etc/opt/adempiere</code>.
| + | |
| − | </p><p>
| + | |
| − | But there is an issue with user-based configuration files for running the client, which are placed as
| + | |
| − | visible files into the current working directory. These should be modified to be located in user's home
| + | |
| − | directories as hidden files (filenames preceded with a .).
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Executable Binaries====
| + | |
| − | </div></div></div><p>
| + | |
| − | Having all executables in one directory makes it easy to include that directory in a user's path so that
| + | |
| − | all commands for a particular package are always available.
| + | |
| − | </p><p>
| + | |
| − | In the case of <span class="productname">Adempiere</span>, there actually are no binaries but only
| + | |
| − | <span class="productname">Java</span> classes which are called from shell scripts, and for ordinary users
| + | |
| − | actually only one such script (<span class="command"><strong>RUN_Adempiere.sh</strong></span>) is required to start the client.
| + | |
| − | And that would normally not be executed from a command line anyway, but rather from a menu on the desktop.
| + | |
| − | </p><p>
| + | |
| − | For administrators, although arguably it is sometimes difficult to understand why a particular script is to be
| + | |
| − | found in <code class="varname">ADEMPIERE_HOME</code>, while another is in <code class="varname">ADEMPIERE_HOME/utils</code>, those
| + | |
| − | are actually the only directories with interesting scripts to run. Furthermore, many of the scripts in the
| + | |
| − | <code class="filename">utils</code> subdirectory actually require a certain structure of helper files and directory trees
| + | |
| − | under them, which would be broken if they were to be moved to a separate <code class="filename">bin</code> directory.
| + | |
| − | </p><p>
| + | |
| − | Executables are thefore best left where they are.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Libraries and Resources====
| + | |
| − | </div></div></div><p>
| + | |
| − | Libraries and resources are exactly the kind of files to be placed under <code class="filename">/opt/adempiere</code>,
| + | |
| − | and the vendor is free to create any structure he wishes under his own subdirectory. So this is FHS compliant, and
| + | |
| − | nothing needs to be changed.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Documentation====
| + | |
| − | </div></div></div><p>
| + | |
| − | <span class="productname">Adempiere</span> mainly uses online documentation for users and a
| + | |
| − | <a class="link" href="http://www.adempiere.com/index.php/ADempiere_ERP" target="_top">wiki</a> for adminstrators and developers.
| + | |
| − | </p><p>
| + | |
| − | However, there is some documentation available in the source code which is not found in the binary distribution.
| + | |
| − | Some of those files might be interesting for administrators or developers and should therefore be placed in
| + | |
| − | <code class="filename">/usr/share/doc/adempiere</code> where they can easily be found.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Data and Variable State Files====
| + | |
| − | </div></div></div><p>
| + | |
| − | <span class="productname">Adempiere</span> does not keep its own data files but rather stores all data in an external
| + | |
| − | database such as <span class="productname">Oracle</span> or <span class="productname">postgreSQL</span>.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Log Files====
| + | |
| − | </div></div></div><p>
| + | |
| − | Although the FHS states that no files should exist outside of the <code class="filename">/opt</code>, <code class="filename">/var/opt</code>,
| + | |
| − | and <code class="filename">/etc/opt</code> hierarchies, it probably makes sense to cover log files with the
| + | |
| − | <span class="quote">“<span class="quote">files which must reside in specific locations to function properly</span>”</span> exception.
| + | |
| − | </p><p>
| + | |
| − | Out of the box, <span class="productname">Adempiere</span>'s log files are scattered over its subdirectories, often
| + | |
| − | with duplicate and redundant information.
| + | |
| − | </p><p>
| + | |
| − | These log files can grow very big over time. If, as would be good practice, a separate partition is mounted on
| + | |
| − | <code class="filename">/opt/adempiere</code>, that partion could easily get filled up with logs. It would be much better
| + | |
| − | to use the operating system's logging facilities with all its advantages (for example, file rotation or remote
| + | |
| − | logging) than clogging up the <span class="productname">Adempiere</span> partition.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Exceptional Files====
| + | |
| − | </div></div></div><p>
| + | |
| − | Other files which would need to reside in specific locations to function properly would include
| + | |
| − | </p><div><dl>
| + | |
| − | ;/etc/rc.d/init.d/adempiere
| + | |
| − | :<p>An init script to start and stop the application server.</p>
| + | |
| − | ;/etc/sysconfig/adempiere
| + | |
| − | :<p>Configuration file for the init script.</p>
| + | |
| − | ;/etc/profile.d/adempiere.sh
| + | |
| − | :<p>A short script to set the <code class="varname">ADEMPIERE_HOME</code> variable system-wide for all users.</p>
| + | |
| − | ;/usr/share/applications/adempiere.desktop
| + | |
| − | :<p>A descriptive file to add a menu item for starting the client on the users' desktop.</p>
| + | |
| − | ;/var/log/adempiere
| + | |
| − | :<p>
| + | |
| − | As previously explained, a central log file used by the system logger to collect and manage all
| + | |
| − | logs in one place.
| + | |
| − | </p></dl></div><p>
| + | |
| − | </p><p>
| + | |
| − | Such files are very specific to <span class="productname">RedHat</span>-like systems and are not included in
| + | |
| − | the vanilla <span class="productname">Adempiere</span> distribution.
| + | |
| − | </p></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Running as Daemon===
| + | |
| − | </div></div></div><p>
| + | |
| − | The standard <span class="productname">Adempiere</span> distribution comes with the <span class="command"><strong>RUN_Server2.sh</strong></span>
| + | |
| − | and <span class="command"><strong>RUN_Server2Stop.sh</strong></span> commands to start respectively stop the application server.<sup>[[#ftn.id3051720|2]]</sup>
| + | |
| − | </p><p>
| + | |
| − | The scripts are designed to run in the foreground dumping log information to the console from which they
| + | |
| − | were started. The administrator is supposed to follow the state of the server by examinig the log messages
| + | |
| − | on the console. Thus the server would be started on one console and left running, and to stop it a new console
| + | |
| − | would need to be opened from which the stop command would be initiated. The administrator would then have to
| + | |
| − | switch back to the original console to verify from the log messages that the server has really stopped.
| + | |
| − | </p><p>
| + | |
| − | While such procedure is acceptable for development purposes, it definitely does not scale well for production
| + | |
| − | environments.
| + | |
| − | </p><p>
| + | |
| − | Apart from being impractical, under <span class="productname">Linux</span> another issue arises that the server would
| + | |
| − | be running with the privileges and limitations of the user who started it, which could be any user or even
| + | |
| − | <code class="code">root</code>, raising very valid security concerns.
| + | |
| − | </p><p>
| + | |
| − | It would be much better to have a designated <code class="code">adempiere</code> user for no other purpose than running the server,
| + | |
| − | being able to start and stop the server with <span class="command"><strong>service adempiere start</strong></span> or
| + | |
| − | <span class="command"><strong>service adempiere stop</strong></span> like any other daemon, and configuring startup and shutdown behavior with
| + | |
| − | <span class="command"><strong>chkconfig</strong></span>.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Desktop Integration===
| + | |
| − | </div></div></div><p>
| + | |
| − | Any user who wants to run the server or client must have the <code class="varname">ADEMPIERE_HOME</code> environment variable
| + | |
| − | set to the correct location. That means <code class="varname">ADEMPIERE_HOME</code> should be set system-wide on both
| + | |
| − | server and client machines.
| + | |
| − | </p><p>
| + | |
| − | And for users who want to run the client, having an item in their desktop menu is surely more comfortable
| + | |
| − | than having to open a console and typing <span class="command"><strong>$ADEMPIERE_HOME/RUN_Adempiere.sh</strong></span>.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Package Management===
| + | |
| − | </div></div></div><p>
| + | |
| − | On <span class="productname">RedHat</span>-like systems, software installation, upgrading, and uninstallation should
| + | |
| − | be managed by RPM. This ensures consistent deployment and allows for centralized management of clients
| + | |
| − | and servers.
| + | |
| − | </p></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==How the Adempiere Source-RPM works==
| + | |
| − | </div></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Preparation===
| + | |
| − | </div></div></div><p>
| + | |
| − | The <span class="productname">Adempiere</span> source code is downloaded from the
| + | |
| − | <a class="link" href="http://adempiere.hg.sourceforge.net/hgweb/adempiere/" target="_top"><span class="productname">Mercurial</span> repository</a> at SourceForge.net, and
| + | |
| − | file formats (end-of line difference between <span class="productname">Windows</span> and <span class="productname">Linux</span>)
| + | |
| − | and file permissions (scripts should be executable) are corrected.
| + | |
| − | </p><p>
| + | |
| − | The standard building behavior is modified so that build results are not e-mailed to anybody,
| + | |
| − | building stops after compilation and does not proceed to actual file installation, and generation
| + | |
| − | of the distributable zip-file (the binary package which is distributed by <span class="productname">Adempiere</span>)
| + | |
| − | is suppressed.
| + | |
| − | </p><p>
| + | |
| − | If required, some quick fixes are applied to solve known issues which need to be addressed before compiling.
| + | |
| − | </p><p>
| + | |
| − | Then a copy of the whole source tree is made. The idea is that two different products should be compiled,
| + | |
| − | one from the pristine source which was downloaded, and one from a source containing additions and patches
| + | |
| − | for customizations. Help and support will generally only be available for the original product, not for any
| + | |
| − | extended or customized versions. By having an RPM with the pristine code available, problems can be
| + | |
| − | replicated in the original product before filing support requests or bug reports.
| + | |
| − | </p><p>
| + | |
| − | Standard patches (those distributed with this Source-RPM) are applied.
| + | |
| − | </p><p>
| + | |
| − | After that, the packager has the opportunity to add his own sources and patches for customizations or local extensions or bugfixes.
| + | |
| − | (Although it would of course be much nicer if the packager would contribute his bugfixes back to the <span class="productname">Adempiere</span>
| + | |
| − | project instead of just silently applying them to his local copy).
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Building===
| + | |
| − | </div></div></div><p>
| + | |
| − | First the orginal source is compiled to build the pristine package.
| + | |
| − | </p><p>
| + | |
| − | Then the customized source is compiled to build the server subpackage.
| + | |
| − | </p><p>
| + | |
| − | Any pdf files found in the original or customized source after compilation are extracted
| + | |
| − | as documentation files.
| + | |
| − | </p><p>
| + | |
| − | If requested, the server is "pre-configured". All parameters which would normally be set after installation
| + | |
| − | when executing <span class="command"><strong>RUN_setup.sh</strong></span> can already be configured now, resulting in a server package which
| + | |
| − | can run out of the box when it is installed on the target machine. This makes the administrator's life very easy,
| + | |
| − | but of course it also means that the resulting RPM is location-specific and can not be distributed publicly.
| + | |
| − | </p><p>
| + | |
| − | The server is then configured to send its log messages to the system logger rather than using local files.
| + | |
| − | </p><p>
| + | |
| − | The client code is extracted from the server package and modified so that the user's properties file is a hidden file
| + | |
| − | in his home directory.
| + | |
| − | </p><p>
| + | |
| − | As a last step, the documentation for the Source-RPM (this text!) is generated.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Packaging===
| + | |
| − | </div></div></div><p>
| + | |
| − | The build results are installed in a root file system as they should appear on the target system when they
| + | |
| − | get installed.
| + | |
| − | </p><p>
| + | |
| − | In addition to the compiled code, some support files are installed for additonal <span class="productname">Linux</span>-specific
| + | |
| − | functionality:
| + | |
| − | </p><p>
| + | |
| − | A file is dropped into <code class="filename">/etc/profile.d</code> to set the <code class="varname">ADEMPIERE_HOME</code> environment
| + | |
| − | variable on a system-wide level.
| + | |
| − | </p><p>
| + | |
| − | An <span class="quote">“<span class="quote">init</span>”</span> script and its configuration file are installed to allow starting up or shutting down
| + | |
| − | or otherwise controlling the server with the <span class="command"><strong>service adempiere start</strong></span> or <span class="command"><strong>service adempiere stop</strong></span>
| + | |
| − | or <span class="command"><strong>chkconfig adempiere</strong></span> commands.
| + | |
| − | </p><p>
| + | |
| − | A desktop file is dropped into <code class="filename">/usr/share/applications</code> to include the <span class="productname">Adempiere</span>
| + | |
| − | client in the users' desktop menu.
| + | |
| − | </p><p>
| + | |
| − | Documentation files are placed into the <code class="filename">/usr/share/doc</code> directory.
| + | |
| − | </p><p>
| + | |
| − | RPM packages are built from this root filesystem (one for client, one for server, one for the pristine product), which can
| + | |
| − | be distributed and installed on other machines.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Installation on the Target System===
| + | |
| − | </div></div></div><p>
| + | |
| − | When the <span class="productname">Adempiere</span> packages are installed on the target machines, their behavior differs
| + | |
| − | depending on the kind of package (client, server, pristine) and the type of installation (installation, upgrade, removal).
| + | |
| − | </p><div><div class="titlepage"><div><div>
| + | |
| − | ====Installation====
| + | |
| − | </div></div></div><div class="informaltable"><a name="tblInstallation"></a><table border="1"><tr><th align="left">Step</th><th align="center">Client</th><th align="center">Server</th><th align="center">Pristine</th></tr><tr><td rowspan="3" align="left">pre-install</td><td align="center">---</td><td align="center">create <code class="code">adempiere</code> user</td><td align="center">---</td></tr><tr><td colspan="3" align="center">create user home directory</td></tr><tr><td colspan="3" align="center">configure rsyslog</td></tr><tr><td align="left">install</td><td colspan="3" align="center">install files</td></tr><tr><td rowspan="2" align="left">post-install</td><td colspan="2" align="center">create ADEMPIERE_HOME symbolic link</td><td align="center">---</td></tr><tr><td align="center">---</td><td align="center">autostart server on system boot</td><td align="center">---</td></tr></table></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Upgrade====
| + | |
| − | </div></div></div><div class="informaltable"><a name="tblUpgrade"></a><table border="1"><tr><th align="left">Step</th><th align="center">Client</th><th align="center">Server</th><th align="center">Pristine</th></tr><tr><td rowspan="3" align="left">pre-install</td><td align="center">---</td><td align="center">create <code class="code">adempiere</code> user</td><td align="center">---</td></tr><tr><td colspan="3" align="center">create user home directory</td></tr><tr><td colspan="3" align="center">configure rsyslog</td></tr><tr><td align="left">install</td><td colspan="3" align="center">install new files</td></tr><tr><td rowspan="2" align="left">post-install</td><td colspan="2" align="center">create <code class="varname">ADEMPIERE_HOME</code> symbolic link</td><td align="center">---</td></tr><tr><td align="center">---</td><td align="center">autostart server on system boot</td><td align="center">---</td></tr><tr><td align="left">pre-uninstall</td><td colspan="3" align="center">---</td></tr><tr><td align="left">uninstall</td><td colspan="3" align="center">remove old files</td></tr><tr><td align="left">post-uninstall</td><td align="center">---</td><td align="center">restart server</td><td align="center">---</td></tr></table></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Removal====
| + | |
| − | </div></div></div><div class="informaltable"><a name="tblRemoval"></a><table border="1"><tr><th align="left">Step</th><th align="center">Client</th><th align="center">Server</th><th align="center">Pristine</th></tr><tr><td rowspan="3" align="left">pre-uninstall</td><td align="center">---</td><td align="center">stop server</td><td align="center">---</td></tr><tr><td colspan="3" align="center">unconfigure autostart of server on system boot if no other server packages are installed</td></tr><tr><td colspan="3" align="center">remove <code class="varname">ADEMPIERE_HOME</code> symbolic link if it points to this installation</td></tr><tr><td align="left">uninstall</td><td colspan="3" align="center">remove old files</td></tr><tr><td rowspan="7" align="left">post-uninstall</td><td colspan="3" align="center">remove installation directory</td></tr><tr><td colspan="3" align="center">unconfigure rsyslog if no more server installations exist</td></tr><tr><td colspan="3" align="center">unconfigure system-wide setting of <code class="varname">ADEMPIERE_HOME</code> if no more server or client installations exist</td></tr><tr><td colspan="3" align="center">remove desktop menu entry if no more server or client installations exist</td></tr><tr><td colspan="3" align="center">remove <code class="varname">ADEMPIERE_HOME</code> symbolic link if no more server or client installations exist</td></tr><tr><td colspan="3" align="center">remove user home directory and documentation if no other installations exist</td></tr><tr><td colspan="3" align="center">create <code class="varname">ADEMPIERE_HOME</code> symbolic link to newest server or client if any server or client installations exist</td></tr></table></div></div></div></div><div class="footnotes"><br><hr width="100" align="left"><div><p><sup>[<span id="ftn.id3050553" class="para">1</span>] </sup>Which means that according to the FHS,
| + | |
| − | <span class="productname">Adempiere</span> should always be installed in <code class="filename">/opt/adempiere</code>.</p></div><div><p><sup>[<span id="ftn.id3051720" class="para">2</span>] </sup>The <span class="quote">“<span class="quote">2</span>”</span> is presumabely a remnant from the days before <span class="productname">Adempiere</span>
| + | |
| − | forked from <span class="productname">Compiere</span>, where these scripts where used to control the new version 2
| + | |
| − | server, as opposed to <span class="command"><strong>RUN_Server.sh</strong></span> and <span class="command"><strong>RUN_ServerStop.sh</strong></span> controlling
| + | |
| − | the old version 1 server, which has since been lost.</p></div></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Preparing the Package Building Environment=
| + | |
| − | </div><div><div class="titlepage"><div><div>
| + | |
| − | ==Required Development Tools==
| + | |
| − | </div></div></div><p>
| + | |
| − | Install the tools required for building the <span class="productname">Adempiere</span> RPM. (This needs to be done as <code class="code">root</code>).
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>yum install rpm-build rpmdevtools gnupg mercurial java-1.6.0-openjdk-devel desktop-file-utils docbook5-style-xsl libxslt fop</strong></span>
| + | |
| − | </p></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==RPM Build Tree==
| + | |
| − | </div></div></div><p>
| + | |
| − | Create the RPM build tree in your home directory.
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>rpmdev-setuptree</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | This command creates the following directory tree required by <span class="command"><strong>rpmbuild</strong></span> and configures your build settings
| + | |
| − | in <code class="filename">~/.rpmmacros</code>
| + | |
| − | </p><pre class="programlisting">
| + | |
| − | rpmbuild
| + | |
| − | +-- BUILD
| + | |
| − | +-- RPMS
| + | |
| − | +-- SOURCES
| + | |
| − | +-- SPECS
| + | |
| − | +-- SRPMS
| + | |
| − | </pre><p>
| + | |
| − | You can move the generated <code class="filename">rpmbuild</code> directory to any place you like, but then you must adjust
| + | |
| − | the <code class="varname">%_topdir</code> setting in <code class="filename">~/.rpmmacros</code> to point to that location.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Digital Signature==
| + | |
| − | </div></div></div><p>
| + | |
| − | For security reasons, the packages you build should be digitally signed. The digital signature allows users to verify
| + | |
| − | that the package has been built by you, a trusted source, and has not been tampered with since then.
| + | |
| − | </p><p>
| + | |
| − | First, generate a public/private key pair with the <span class="command"><strong>gpg --gen-key</strong></span> command:
| + | |
| − | </p><pre class="programlisting">
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>gpg --gen-key</strong></span>
| + | |
| − | gpg (GnuPG) 1.4.10; Copyright (C) 2008 Free Software Foundation, Inc.
| + | |
| − | This is free software: you are free to change and redistribute it.
| + | |
| − | There is NO WARRANTY, to the extent permitted by law.
| + | |
| − | | + | |
| − | Please select what kind of key you want:
| + | |
| − | (1) RSA and RSA (default)
| + | |
| − | (2) DSA and Elgamal
| + | |
| − | (3) DSA (sign only)
| + | |
| − | (4) RSA (sign only)
| + | |
| − | Your selection? <strong><code>1</code></strong>
| + | |
| − | RSA keys may be between 1024 and 4096 bits long.
| + | |
| − | What keysize do you want? (2048) <strong><code>2048</code></strong>
| + | |
| − | Requested keysize is 2048 bits
| + | |
| − | Please specify how long the key should be valid.
| + | |
| − | 0 = key does not expire
| + | |
| − | <n> = key expires in n days
| + | |
| − | <n>w = key expires in n weeks
| + | |
| − | <n>m = key expires in n months
| + | |
| − | <n>y = key expires in n years
| + | |
| − | Key is valid for? (0) <strong><code>0</code></strong>
| + | |
| − | Key does not expire at all
| + | |
| − | Is this correct? (y/N) <strong><code>y</code></strong>
| + | |
| − | | + | |
| − | You need a user ID to identify your key; the software constructs the user
| + | |
| − | ID from the Real Name, Comment and Email Address in this form:
| + | |
| − | "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
| + | |
| − | | + | |
| − | Real name: <strong><code>www.mycompany.com</code></strong>
| + | |
| − | Email address: <strong><code>devnull@mycompany.com</code></strong>
| + | |
| − | Comment: <strong><code>rpm signature</code></strong>
| + | |
| − | | + | |
| − | You selected this USER-ID:
| + | |
| − | "www.mycompany.com (rpm signature) <devnull@mycompany.com>"
| + | |
| − | | + | |
| − | Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <strong><code>O</code></strong>
| + | |
| − | You need a Passphrase to protect your secret key.
| + | |
| − | | + | |
| − | Enter passphrase: <strong><code><a name="uiPassphrase"></a>secret passphrase</code></strong>
| + | |
| − | Repeat passphrase: <strong><code>secret passphrase</code></strong>
| + | |
| − | | + | |
| − | We need to generate a lot of random bytes. It is a good idea to perform
| + | |
| − | some other action (type on the keyboard, move the mouse, utilize the
| + | |
| − | disks) during the prime generation; this gives the random number
| + | |
| − | generator a better chance to gain enough entropy.
| + | |
| − | .+++++
| + | |
| − | ........+++++
| + | |
| − | ..+++++
| + | |
| − | gpg: key F9D8EE90 marked as ultimately trusted
| + | |
| − | public and secret key created and signed.
| + | |
| − | | + | |
| − | gpg: checking the trustdb
| + | |
| − | gpg: 3 marginal(s) needed, 1 complete(s) needed, classic trust model
| + | |
| − | gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
| + | |
| − | pub 2048R/F9D8EE90 2010-10-17
| + | |
| − | Key fingerprint = 983D 704A 024A 861F 9FCB 5CA2 4875 7B66 F9D8 EE90
| + | |
| − | uid www.mycompany.com (rpm signature) <devnull@mycompany.com>
| + | |
| − | sub 2048R/496CD9ED 2010-10-17
| + | |
| − | </pre><p>
| + | |
| − | Next, the public key needs to be extracted:
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>gpg --export --armor www.mycompany.com > MYCOMPANY-RPM-GPG-KEY</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | This file needs to be publicly distributed so that users can verify the signature of the RPM packages which you built and signed.
| + | |
| − | </p><p>
| + | |
| − | Finally, you need to configure <span class="command"><strong>rpmbuild</strong></span> to use the signature you just created
| + | |
| − | by adding the <code class="varname">%_signature</code> and <code class="varname">%_gpg_name</code> macros to the <code class="filename">.rpmmacros</code>
| + | |
| − | file in your home directory. The file should now look something like this:
| + | |
| − | </p><pre class="programlisting">
| + | |
| − | %_topdir /home/<em>username</em>/rpmbuild
| + | |
| − | %_signature gpg
| + | |
| − | %_gpg_name www.mycompany.com (rpm signature) <devnull@mycompany.com>
| + | |
| − | …
| + | |
| − | …
| + | |
| − | </pre></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Using the Adempiere SRPM=
| + | |
| − | </div><div><div class="titlepage"><div><div>
| + | |
| − | ==Installing the Source-RPM==
| + | |
| − | </div></div></div><p>
| + | |
| − | Once your package building environment has been set up, you can download and unpack the <span class="productname">Adempiere</span>
| + | |
| − | source RPM:
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>wget -q http://adempiere.hg.sourceforge.net/hgroot/adempiere/adempiere/raw-file/tip/utils/unix/adempiere.srpm</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>rpm -ivH adempiere.srpm</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | The source files will have been installed in <code class="filename">~/rpmbuild/SOURCES</code>, and the specification file ("Spec" file)
| + | |
| − | in <code class="filename">~/rpmbuild/SPECS/adempiere.spec</code>
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Configuring the Build Process==
| + | |
| − | </div></div></div><p>
| + | |
| − | Build behavior is controlled by various parameters which are set at the beginning of the Spec File.
| + | |
| − | See <a class="link" href="#apndxA" title="Appendix A. Configuration Parameters">Appendix A</a> for a detailed description.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Adding Customizations==
| + | |
| − | </div></div></div><p>
| + | |
| − | Additional sources and patches can be added to the <code class="filename">SOURCES</code> directory to apply extensions and
| + | |
| − | customizations to the <span class="productname">Adempiere</span> source code.
| + | |
| − | </p><p>
| + | |
| − | As new files are added, the <code class="filename">SOURCES</code> directory quickly gets very messy.
| + | |
| − | For this reason, the files distributed with the Source-RPM are prefixed with sXXX_ (for sources)
| + | |
| − | and pXXX_ (for patches), where XXX corresponds to the patch or source number in the Spec File.
| + | |
| − | Users are encouraged to name their sources and patches following the same naming scheme.
| + | |
| − | </p><p>
| + | |
| − | Sources and patches must be listed in the Spec File using the <span class="command"><strong>Source<number>: filename</strong></span>
| + | |
| − | and <span class="command"><strong>Patch<number>: filename</strong></span> pragmas.
| + | |
| − | </p><p>
| + | |
| − | Source and patch numbers 0-99 are reserved for the maintainer of the <span class="productname">Adempiere</span> source RPM,
| + | |
| − | so you may add source files and patches starting with number 100.
| + | |
| − | </p><pre class="programlisting">
| + | |
| − | …
| + | |
| − | …
| + | |
| − | # Sources
| + | |
| − | # -------
| + | |
| − | | + | |
| − | # standard sources
| + | |
| − | …
| + | |
| − | …
| + | |
| − | | + | |
| − | # your custom sources come here
| + | |
| − | # (start with number 100)
| + | |
| − | Source100: s100_MMyModel.java
| + | |
| − | Source101: s101_myScript.sh
| + | |
| − | | + | |
| − | | + | |
| − | # Patches
| + | |
| − | # -------
| + | |
| − | | + | |
| − | # standard patches
| + | |
| − | …
| + | |
| − | …
| + | |
| − | | + | |
| − | # your custom patches come here
| + | |
| − | # (start with number 100)
| + | |
| − | Patch100: p100_myPatch1.patch
| + | |
| − | Patch101: p101_myPatch2.patch
| + | |
| − | …
| + | |
| − | …
| + | |
| − | </pre><p>
| + | |
| − | The sources and patches thus defined in the Spec File's preamble must be installed or applied in the %prep section,
| + | |
| − | which is usually done with the <span class="command"><strong>install</strong></span> shell command and <span class="command"><strong>%patch</strong></span> macro.
| + | |
| − | </p><pre class="programlisting">
| + | |
| − | …
| + | |
| − | …
| + | |
| − | %prep
| + | |
| − | …
| + | |
| − | …
| + | |
| − | cd $rpmBuildDir/source/custom
| + | |
| − | | + | |
| − | # standard patches
| + | |
| − | # ----------------
| + | |
| − | …
| + | |
| − | …
| + | |
| − | | + | |
| − | # install your sources here
| + | |
| − | # -------------------------
| + | |
| − | install -pD -m0644 %{SOURCE100} base/src/org/adempiere/model/MMyModel.java
| + | |
| − | install -pD -m0755 %{SOURCE101} utils/myScript.sh
| + | |
| − | | + | |
| − | # apply your patches here
| + | |
| − | # -----------------------
| + | |
| − | %patch -P100 -p1
| + | |
| − | %patch -P101 -p1
| + | |
| − | …
| + | |
| − | …
| + | |
| − | </pre><p>
| + | |
| − | The <span class="command"><strong>install</strong></span> command works like <span class="command"><strong>cp</strong></span>, with the addition that it will create
| + | |
| − | all leading components in the path to the target file if they are missing (<code class="option">-D</code> option), preserve
| + | |
| − | the source file's timestamp (<code class="option">-p</code> option), and set the permission mode of the target file
| + | |
| − | (<code class="option">-m</code> option).
| + | |
| − | </p><p>
| + | |
| − | The <span class="command"><strong>%patch</strong></span> macro invokes the <span class="command"><strong>patch</strong></span> command to apply patches to the source.
| + | |
| − | The patch file number is specified with the <code class="option">-P</code> (upper case P) option, and the <code class="option">-p</code>
| + | |
| − | (lower case p) option tells the patch command how many leading slashes and directories are to be omitted from
| + | |
| − | filenames in the patch file. This will be explained in the <a class="link" href="#parPatches">next chapter</a>.
| + | |
| − | </p><p>
| + | |
| − | For building <span class="productname">Adempiere</span> packages, the <span class="command"><strong>%patch</strong></span> macro has been extended
| + | |
| − | to accept following additional parameters:
| + | |
| − | </p><div><dl>
| + | |
| − | ;-F fuzz factor
| + | |
| − | :<p>
| + | |
| − | Use the given <em>fuzz factor</em>
| + | |
| − | </p>
| + | |
| − | ;-d directory
| + | |
| − | :<p>
| + | |
| − | change to <em>directory</em> before doing anything
| + | |
| − | </p>
| + | |
| − | ;-a filename
| + | |
| − | :<p>
| + | |
| − | Apply patch only if <em>filename</em> exists.
| + | |
| − | </p><p>
| + | |
| − | If <em>filename</em> starts with a <code class="constant">/</code>, it describes an
| + | |
| − | absolute path, otherwise it is relative to <code class="varname">RPM_BUILD_DIR</code>.
| + | |
| − | </p>
| + | |
| − | ;-x regular expression
| + | |
| − | :<p>
| + | |
| − | requires <span class="command"><strong>-a</strong></span>.
| + | |
| − | </p><p>
| + | |
| − | Apply patch only if <em>regular expression</em> exists in <em>filename</em>.
| + | |
| − | </p><p>
| + | |
| − | If <em>regular expression</em> starts with a <code class="constant">!</code>, apply patch only
| + | |
| − | if <em>regular expression</em> does <span class="emphasis"><em>not</em></span> exist in <em>filename</em>.
| + | |
| − | </p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Building the RPM packages==
| + | |
| − | </div></div></div><p>
| + | |
| − | Packages are generated using the <span class="command"><strong>rpmbuild --sign -b… /path/to/adempiere.spec</strong></span> command,
| + | |
| − | where the <code class="option">--sign</code> option will sign the package using the
| + | |
| − | <a class="link" href="#secGpgSign" title="Digital Signature">gpg-signature we created earlier</a>, and the stage up to which the packages are
| + | |
| − | built is defined with the <code class="option">-b…</code> switch:
| + | |
| − | </p><div><dl>
| + | |
| − | ;-bp
| + | |
| − | :<p>
| + | |
| − | build up to "prep" phase only, which means downloading the source and applying patches.
| + | |
| − | </p>
| + | |
| − | ;-bc
| + | |
| − | :<p>
| + | |
| − | build up to "build" phase only, which means compiling the source.
| + | |
| − | </p>
| + | |
| − | ;-bi
| + | |
| − | :<p>
| + | |
| − | build up to "install" phase only, the resulting files are installed in a directory structure as
| + | |
| − | they would be on the target machine.
| + | |
| − | </p>
| + | |
| − | ;-bb
| + | |
| − | :<p>
| + | |
| − | build binary packages (adempiere-….noarch.rpm, adempiere-server-….noarch.rpm, adempiere-client-….noarch.rpm).
| + | |
| − | </p>
| + | |
| − | ;-bs
| + | |
| − | :<p>
| + | |
| − | build source package (adempiere-….srpm).
| + | |
| − | </p>
| + | |
| − | ;-ba
| + | |
| − | :<p>
| + | |
| − | build all packages (both binary and source).
| + | |
| − | </p></dl></div><div class="informalexample"><p>
| + | |
| − | <span class="command"><strong>rpmbuild --sign -ba ~/rpmbuild/SPECS/adempiere.spec</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | The resulting RPM packages can be found in <code class="filename">~/rpmbuild/RPMS/noarch</code>, and the source RPM in
| + | |
| − | <code class="filename">~/rpmbuild/SRPMS</code>.
| + | |
| − | </p><p>
| + | |
| − | When using <code class="option">--sign</code>, <span class="command"><strong>rpmbuild</strong></span> will prompt you for a passphrase. Enter the same
| + | |
| − | phrase which was used when the <a class="link" href="#uiPassphrase">gpg key was generated</a>.
| + | |
| − | </p></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Creating Patches=
| + | |
| − | </div><p>
| + | |
| − | Patches are text files generated by the <span class="command"><strong>diff</strong></span> tool which compares files or directories and records
| + | |
| − | the differences in a certain format. Those differences can then be re-applied to the original source using <span class="command"><strong>patch</strong></span>.
| + | |
| − | </p><p>
| + | |
| − | To create a patch file, you therefore need the original source and a copy. You can program your changes by editing,
| + | |
| − | adding, or deleting files in the copy. Then use <span class="command"><strong>diff</strong></span> to compare the original source with the changes
| + | |
| − | you made in the copy and record those changes in a patch file.
| + | |
| − | </p><p>
| + | |
| − | Normally you would want to add your changes to source files to which all previous patches have already been applied. You can obtain
| + | |
| − | the patched source code by using the <code class="option">-bp</code> option with <span class="command"><strong>rpmbuild</strong></span>, which downloads the code and applies all
| + | |
| − | patches.
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt">$ </code> <span class="command"><strong>rpmbuild -bp ~/rpmbuild/SPECS/adempiere.spec</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | Then you can copy the source directory to new locations, one ending on <code class="filename">.orig</code> and the other ending on <code class="filename">.new</code>.
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt">$ </code> <span class="command"><strong>cp -r ~/rpmbuild/BUILD/adempiere-…/source/custom adempiere.orig</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt">$ </code> <span class="command"><strong>cp -r ~/rpmbuild/BUILD/adempiere-…/source/custom adempiere.new</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | Start hacking your heart out and make any changes you want in <code class="filename">adempiere.new</code>.
| + | |
| − | <sup>[[#ftn.id3053852|3]]</sup>
| + | |
| − | When you are done, go back to the parent directory and run <span class="command"><strong>diff</strong></span> to compare
| + | |
| − | <code class="filename">adempiere.orig</code> with <code class="filename">adempiere.new</code>
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt">$ </code> <span class="command"><strong>diff -durNbB adempiere.orig adempiere.new > myPatch.patch</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | These are the options used in above <span class="command"><strong>diff</strong></span> command:
| + | |
| − | </p><div><dl>
| + | |
| − | ;-d
| + | |
| − | :<p>forces <span class="command"><strong>diff</strong></span> to search for smaller sets of changes than it normally would</p>
| + | |
| − | ;-u
| + | |
| − | :<p>generates unified output format, which is required by <span class="command"><strong>patch</strong></span></p>
| + | |
| − | ;-r
| + | |
| − | :<p>recursively compare subdirectories</p>
| + | |
| − | ;-N
| + | |
| − | :<p>if a file is only found in one directory, treat it as present but empty in the other directory</p>
| + | |
| − | ;-b
| + | |
| − | :<p>ignores changes only in whitespace</p>
| + | |
| − | ;-B
| + | |
| − | :<p>ignores changes only in blank lines</p></dl></div><p>
| + | |
| − | </p><p>
| + | |
| − | The resulting patch file can be added to the <code class="filename">SOURCES</code> directory and listed in the Spec File as
| + | |
| − | <a class="link" href="#secAddCustom" title="Adding Customizations">previously explained</a>.
| + | |
| − | </p><p><a name="parPatches"></a>
| + | |
| − | Note that when the patch file was created, you were in the parent directory which contains the source directory tree. But when the
| + | |
| − | patch is being applied by <span class="command"><strong>rpmbuild</strong></span>, you will actually be inside the source directory tree. Therefore, the first
| + | |
| − | directory component of filenames generated by <span class="command"><strong>diff</strong></span> must be ignored when running the <span class="command"><strong>patch</strong></span>
| + | |
| − | command. This is achieved by passing <code class="option">-p1</code> to <span class="command"><strong>patch</strong></span>.
| + | |
| − | </p><div class="footnotes"><br><hr width="100" align="left"><div><p><sup>[<span id="ftn.id3053852" class="para">3</span>] </sup>
| + | |
| − | Be careful not to actually compile the code! You only want to save changes made to the source code.
| + | |
| − | But if you compile the code, many new files will be created which do not exist in the original source, and
| + | |
| − | <span class="command"><strong>diff</strong></span> would regard all of those files as additions you made to the source.
| + | |
| − | </p></div></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Distributing RPM Packages=
| + | |
| − | </div><div><div class="titlepage"><div><div>
| + | |
| − | ==Installing with RPM==
| + | |
| − | </div></div></div><p>
| + | |
| − | The binary packages generated by <span class="command"><strong>rpmbuild</strong></span> can now be installed on target
| + | |
| − | machines using the <span class="command"><strong>rpm</strong></span> command. Before doing so, the public GPG key must be
| + | |
| − | loaded into the rpm database. Both must be done as <code class="code">root</code>.
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>rpm --import MYCOMPANY-RPM-GPG-KEY</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>rpm --ivH adempiere-server-….noarch.rpm</strong></span>
| + | |
| − | </p><p>
| + | |
| − | or
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>rpm --ivH adempiere-client-….noarch.rpm</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | But of course it would be much more efficient to have a central repository from which client
| + | |
| − | machines can use tools like <span class="command"><strong>yum</strong></span> for automatic installation and upgrading.
| + | |
| − | </p><p>
| + | |
| − | Distributing the server package through a central yum repository might not be such a good idea, especially
| + | |
| − | if it was built using pre-configured settings. That would enable anybody to download the server package
| + | |
| − | and access critical information such us database passwords. And anyway, servers should always be upgraded
| + | |
| − | manually.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Creating a YUM Repository==
| + | |
| − | </div></div></div><p>
| + | |
| − | A web server is needed to distribute packages from a yum repository. The <span class="command"><strong>httpd</strong></span> server can be
| + | |
| − | installed using <span class="command"><strong>yum</strong></span>, and for our purposes it can be started out of the box without
| + | |
| − | having to configure it. Below commands have to be run as <code class="code">root</code>.
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>yum install httpd createrepo</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>service httpd start</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | Create an <code class="filename">adempiere</code> directory under <code class="filename">/var/www/html</code>, and copy the
| + | |
| − | GPG public key and the RPM packages to be distributed into it. Make sure that everybody has read permissions
| + | |
| − | for those files.
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>mkdir -p /var/www/html/adempiere</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>cp MYCOMPANY-RPM-GPG-KEY /var/www/html/adempiere/</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>cp adempiere-….noarch.rpm /var/www/html/adempiere/</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>chmod o+x /var/www/html/adempiere</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>chmod -R o+r /var/www/html/adempiere</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | Create the repository by executing <span class="command"><strong>createrepo .</strong></span> (the last dot is important!) inside
| + | |
| − | <code class="filename">/var/www/html/adempiere</code>
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>cd /var/www/html/adempiere</strong></span>
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>createrepo .</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | Your yum repository is now up and running and can be accessed from client machines.
| + | |
| − | </p><p>
| + | |
| − | For distributing upgrades, simply drop the new RPM files into the repository and run
| + | |
| − | <span class="command"><strong>createrepo .</strong></span> again.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Installing with YUM==
| + | |
| − | </div></div></div><p>
| + | |
| − | Before being able to use your new <span class="productname">Adempiere</span> repository, client
| + | |
| − | machines must be aware that it exists. As <code class="code">root</code>, create a file <code class="filename">adempiere.repo</code>
| + | |
| − | in <code class="filename">/etc/yum.repos.d</code> with following contents:
| + | |
| − | </p><pre class="programlisting">
| + | |
| − | [adempiere]
| + | |
| − | name=Adempiere
| + | |
| − | baseurl=http://<em>address.of.your.web.server</em>/adempiere
| + | |
| − | enabled=1
| + | |
| − | </pre><p>
| + | |
| − | And of course the public key for signature verification must be imported into the RPM database
| + | |
| − | (needs to be done as <code class="code">root</code>):
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>rpm --import http://<em>address.of.your.web.server</em>/adempiere/MYCOMPANY-RPM-GPG-KEY</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | Now <span class="command"><strong>yum</strong></span> can be used to install, upgrade, or remove your <span class="productname">Adempiere</span> packages:
| + | |
| − | </p><div class="informalexample"><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>yum install adempiere-client</strong></span>
| + | |
| − | </p><p>
| + | |
| − | or
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>yum upgrade adempiere-client</strong></span>
| + | |
| − | </p><p>
| + | |
| − | or
| + | |
| − | </p><p>
| + | |
| − | <code class="prompt"># </code><span class="command"><strong>yum remove adempiere-client</strong></span>
| + | |
| − | </p></div><p>
| + | |
| − | If the client machine has daily run of <span class="command"><strong>yum</strong></span> enabled, it will automatically upgrade to the
| + | |
| − | newest package published in the <code class="filename">adempiere</code> repository.
| + | |
| − | </p></div><div><div class="titlepage"><div><div>
| + | |
| − | =<span id="apndxA">Configuration Parameters</span>=
| + | |
| − | </div></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==General Settings==
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;name
| + | |
| − | :<p>The name of the resulting package</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global name adempiere</code></p>
| + | |
| − | ;company
| + | |
| − | :<p>The name of the packager (your company)</p><p>default: <code class="constant">custom</code></p><p>example: <code class="code">%global company Some Company, Inc.</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Compile Settings==
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;applyQuickFix
| + | |
| − | :<p>whether quick fixes should be applied</p><p>Sometimes the source does not compile and some quick fixes or workarounds must be applied. The script <code class="filename">SOURCES/s041_quickFix.sh</code> is called to apply such workarounds.</p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">0</code> = do not apply quick Fixes</p></li><li><p><code class="constant">1</code> = apply quick Fixes</p></li></ul></div><p>
| + | |
| − | </p><p>default: <code class="constant">1</code></p><p>example: <code class="code">%global applyQuickFix 1</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Version Settings==
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;version
| + | |
| − | :<p>the <span class="productname">Adempiere</span> version to download and compile</p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">current</code>, <code class="constant">head</code> = download newest files of the current <span class="productname">Adempiere</span> version</p></li><li><p><code class="constant">release</code> = download original files of the current <span class="productname">Adempiere</span> version as it was originally released</p></li><li><p><code class="constant">previous</code> = download newest files of the previous <span class="productname">Adempiere</span> version (just before it changed to the current version)</p></li><li><p><em>version</em> = specific <span class="productname">Adempiere</span> version to download</p></li></ul></div><p>
| + | |
| − | </p><p>
| + | |
| − | Note that versions are relative to the current branch (see <a class="link" href="#hgBranch">hgBranch</a>) in the <span class="productname">Mercurial</span> repository.
| + | |
| − | </p><p>
| + | |
| − | When comparing the <span class="productname">Adempiere</span> version with tags in the <span class="productname">Mercurial</span> repository,
| + | |
| − | both are converted to lower-case, all non-alphanumeric characters are stripped, and any "adempiere" or "release"
| + | |
| − | prepending the version number are removed. Thus <code class="constant">release-2.5.3b-initial</code> becomes <code class="constant">253binitial</code>,
| + | |
| − | <code class="constant">adempiere340-trunk-frozen</code> becomes <code class="constant">340trunkfrozen</code>, and
| + | |
| − | <code class="constant">Adempiere360LTS</code> becomes <code class="constant">360lts</code>.
| + | |
| − | </p><p>default: <code class="constant">current</code></p><p>example: <code class="code">%global version 360lts</code></p><p>
| + | |
| − | Alternatively, it is possible to directly specify a <span class="productname">Mercurial</span> revision.
| + | |
| − | In this case it is assumed that you know what you are doing, and no further sanity checks are performed.
| + | |
| − | This also overrides any settings in the <a class="link" href="#hgBranch">hgBranch</a> parameter.
| + | |
| − | </p><p>
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">tip</code> = download the current <span class="productname">Mercurial</span> tip</p></li><li><p><code class="constant">hg</code><em>revision</em> = download specific <span class="productname">Mercurial</span> revision</p></li></ul></div><p>
| + | |
| − | </p><p>
| + | |
| − | Prefixing the version information with <code class="constant">hg</code> will prevent such transformation and it will be treated
| + | |
| − | as literal string.
| + | |
| − | </p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Mercurial Settings==
| + | |
| − | </div></div></div><p>
| + | |
| − | <span class="productname">Mercurial</span> is needed to download the source code as well as gather information on the version.
| + | |
| − | </p><div><dl>
| + | |
| − | ;hgOptions
| + | |
| − | :<p>general options to use with the hg command</p><p>default: <code class="constant">--noninteractive --encoding utf8</code></p><p>example: <code class="code">%global hgOptions --quiet --noninteractive --encoding utf8</code></p>
| + | |
| − | ;hgRepository
| + | |
| − | :<p>URL of the source code repository</p><p>default: <code class="constant">http://adempiere.hg.sourceforge.net:8000/hgroot/adempiere/adempiere</code></p><p>example: <code class="filename">%global hgRepository http://adempiere.hg.sourceforge.net/hgroot/adempiere/adempiere</code></p>
| + | |
| − | ;hgBranch
| + | |
| − | :<p>Named branch in the source code repository</p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">master</code> = the main stable branch containing official releases</p></li><li><p><code class="constant">development</code> = the main development branch with newest features and bugfixes</p></li><li><p><code class="constant">release/</code><em>name</em> = temporary branch with "frozen" code of the next release candidate</p></li><li><p><code class="constant">hotfix/</code><em>name</em> = temporary branch for fixing bugs found in live production version of master branch</p></li><li><p><em>name</em> = any other named branch</p></li></ul></div><p>
| + | |
| − | </p><p>default: <code class="constant">master</code></p><p>example: <code class="code">%global hgBranch master</code></p>
| + | |
| − | ;hgVersionFile
| + | |
| − | :<p>the file from which to read version information</p><p>default: <code class="constant">base/src/org/compiere/Adempiere.java</code></p><p>example: <code class="code">%global hgVersionFile base/src/org/compiere/Adempiere.java</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Adempiere User Settings==
| + | |
| − | </div></div></div><p>OS level environment settings for the 'adempiere' user</p><div><dl>
| + | |
| − | ;userDir
| + | |
| − | :<p>the home directory of the adempiere user</p><p>(this will be the parent directory of <code class="varname">ADEMPIERE_HOME</code>)</p><p>default: <code class="constant">/opt/adempiere</code></p><p>example: <code class="code">%global userDir /opt/adempiere</code></p>
| + | |
| − | ;adempiereHome
| + | |
| − | :<p>the location of <code class="varname">ADEMPIERE_HOME</code></p><p>If starting with a /, it is the absolute path to <code class="varname">ADEMPIERE_HOME</code>. Otherwise it will be a subdirectory under <code class="varname">%{userDir}</code>.</p><p>Note that <code class="varname">%{adempiereHome}</code> will not actually be a directory, but a symbolic link.</p><p>The package will be installed under <code class="varname">%{userDir}</code> with version information, for example
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="filename">/opt/adempiere/adempiere360lts</code> for the pristine package</p></li><li><p><code class="filename">/opt/adempiere/server360lts</code> for the server package</p></li><li><p><code class="filename">/opt/adempiere/client360lts</code> for the client package</p></li></ul></div><p>
| + | |
| − | </p><p>Then a symbolic link will be created from the package directory to <code class="varname">%{adempiereHome}</code>, for example
| + | |
| − | </p><div class="informalexample"><p>ln -s /opt/adempiere/server360lts /opt/adempiere/adempiere</p></div><p>
| + | |
| − | </p><p>
| + | |
| − | This way it is possible to have different packages and versions installed on the same machine,
| + | |
| − | and by changing the symbolic link you can choose which version to run.
| + | |
| − | </p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global adempiereHome /opt/adempiere/adempiere</code></p>
| + | |
| − | ;userName
| + | |
| − | :<p>the name of the adempiere user</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global userName adempiere</code></p>
| + | |
| − | ;userID
| + | |
| − | :<p>the user ID number for the adempiere user</p><p>If the requested user ID is already taken, the next available system ID will be used.</p><p>values: <code class="constant">200</code> <= x < <code class="constant">500</code></p><p>default: <code class="constant">215</code></p><p>example: <code class="code">%global userID 215</code></p>
| + | |
| − | ;groupName
| + | |
| − | :<p>the adempiere user's private group name</p><p>default: same as <code class="varname">%{userName}</code></p><p>example: <code class="code">%global groupName adempiere</code></p>
| + | |
| − | ;groupID
| + | |
| − | :<p>the primary group ID number for the adempiere user</p><p>If the requested group ID is already taken, the next available system ID will be used.</p><p>values: <code class="constant">200</code> <= x < <code class="constant">500</code></p><p>default: <code class="constant">215</code></p><p>example: <code class="code">%global groupID 215</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Pristine Package Settings==
| + | |
| − | </div></div></div><p>The pristine package is the release as distributed by <span class="productname">Adempiere</span> without any extensions or patches. It can be used for testing before filing support requests or bug reports.</p><p>It contains both server and client, and it is not pre-configured.</p><div><dl>
| + | |
| − | ;buildPristine
| + | |
| − | :<p>whether to build the pristine package</p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">0</code> = do not build the pristine package</p></li><li><p><code class="constant">1</code> = build the pristine package</p></li></ul></div><p>
| + | |
| − | </p><p>default: <code class="constant">0</code></p><p>example: <code class="code">%global buildPristine 0</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Client Package Settings==
| + | |
| − | </div></div></div><p>The client package is installed on remote machines.</p><p>It includes desktop menu entries for connection to the server.</p><p>The client package is a custom release to which patches and extensions are applied.</p><div><dl>
| + | |
| − | ;buildClient
| + | |
| − | :<p>whether to build the client package</p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">0</code> = do not build the client package</p></li><li><p><code class="constant">1</code> = build the client package</p></li></ul></div><p>
| + | |
| − | </p><p>default: <code class="constant">1</code></p><p>example: <code class="code">%global buildClient 1</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Server Package Settings==
| + | |
| − | </div></div></div><p>The server package is the live server. It also includes its own client.</p><p>The server package is a custom release to which patches and extensions are applied.</p><div><dl>
| + | |
| − | ;buildServer
| + | |
| − | :<p>whether to build the server package</p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">0</code> = do not build the server package</p></li><li><p><code class="constant">1</code> = build the server package</p></li></ul></div><p>
| + | |
| − | </p><p>default: <code class="constant">1</code></p><p>example: <code class="code">%global buildServer 1</code></p>
| + | |
| − | ;preconfigureServer
| + | |
| − | :<p>whether to pre-configure the server so that it will run out of the box without executing <span class="command"><strong>./RUN_Setup.sh</strong></span></p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">0</code> = do not pre-configure the server package</p></li><li><p><code class="constant">1</code> = pre-configure the server package</p></li></ul></div><p>
| + | |
| − | </p><p>default: <code class="constant">0</code></p><p>example: <code class="code">%global preconfigureServer 0</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Server Configuration Parameters==
| + | |
| − | </div></div></div><p>These parameters are used for pre-configuring the server</p><div><div class="titlepage"><div><div>
| + | |
| − | ===Certificate Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;serverFQDN
| + | |
| − | :<p>The fully qualified domain name of the server</p><p>This string is used to identify the application server as well generate default entries for mail and database server.</p><p>default: <code class="constant">localhost.localdomain</code></p><p>example: <code class="code">%global serverFQDN myAppServer.mydomain.com</code></p>
| + | |
| − | ;keystore
| + | |
| − | :<p>the server's keystore file (relative to <code class="varname">ADEMPIERE_HOME</code>)</p><p>default: <code class="constant">keystore/myKeystore</code></p><p>example: <code class="code">%global keystore keystore/myKeystore</code></p>
| + | |
| − | ;keystorePass
| + | |
| − | :<p>the password for the server's keystore</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global keystorePass adempiere</code></p>
| + | |
| − | ;keystoreCN
| + | |
| − | :<p>The CN (common name) component of the DN (distinguished name) for the server's keystore.</p><p>default: name portion of <code class="varname">serverFQDN</code></p><p>example: <code class="code">%global keystoreCN myAppServer</code></p>
| + | |
| − | ;keystoreOU
| + | |
| − | :<p>The OU (organizational unit) component of the DN (distinguished name) for the server's keystore.</p><p>default: name of currently logged-in user</p><p>example: <code class="code">%global keystoreOU myName</code></p>
| + | |
| − | ;keystoreO
| + | |
| − | :<p>The O (organization) component of the DN (distinguished name) for the server's keystore.</p><p>default: <code class="constant">AdempiereUser</code></p><p>example: <code class="code">%global keystoreO AdempiereUser</code></p>
| + | |
| − | ;keystoreL
| + | |
| − | :<p>The L (location) component of the DN (distinguished name) for the server's keystore.</p><p>default: <code class="constant">myTown</code></p><p>example: <code class="code">%global keystoreL myTown</code></p>
| + | |
| − | ;keystoreST
| + | |
| − | :<p>The ST (state) component of the DN (distinguished name) for the server's keystore.</p><p>default: <code class="constant">myState</code></p><p>example: <code class="code">%global keystoreST myState</code></p>
| + | |
| − | ;keystoreC
| + | |
| − | :<p>The C (country) component of the DN (distinguished name) for the server's keystore.</p><p>default: country from system's <code class="varname">LANG</code> setting in <code class="filename">/etc/sysconfig/i18n</code></p><p>example: <code class="code">%global keystoreC US</code></p>
| + | |
| − | ;keystoreCodeAlias
| + | |
| − | :<p>the certificate alias for code signing on the server</p><p>Note that although this is a configurable parameter, the alias 'adempiere' is hardcoded in some source files, so it might be a bad idea to change it.</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global keystoreCodeAlias adempiere</code></p>
| + | |
| − | ;keystoreWebAlias
| + | |
| − | :<p>the certificate alias for secure web connections to the server</p><p>Note that although this is a configurable parameter, the alias 'adempiere' is hardcoded in some source files, so it might be a bad idea to change it.</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global keystoreWebAlias adempiere</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Java Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;javaType
| + | |
| − | :<p>the Java type installed on the server</p><p>Note that ibm is not implemented yet, and there are still some issues with openJDK.</p><p>values: <code class="constant">sun</code>, <code class="constant">mac</code>, <code class="constant">ibm</code>, <code class="constant">OpenJDK</code></p><p>default: <code class="constant">OpenJDK</code></p><p>example: <code class="code">%global javaType OpenJDK</code></p>
| + | |
| − | ;javaHome
| + | |
| − | :<p>the Java path on the server</p><p>default: <code class="constant">/usr/lib/jvm/java-openjdk</code></p><p>example: <code class="code">%global javaHome /usr/lib/jvm/java-openjdk</code></p>
| + | |
| − | ;javaOptions
| + | |
| − | :<p>options with which to start the virtual machine under which Adempiere is run</p><p>(see Java documentation)</p><p>default: <code class="constant">-Xms64M -Xmx512M</code></p><p>example: <code class="code">%global javaOptions -Xms64M -Xmx512M</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Application Server Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;serverType
| + | |
| − | :<p>the type of application server</p><p>values: <code class="constant">jboss</code>, <code class="constant">glassfish</code></p><p>default: <code class="constant">jboss</code></p><p>example: <code class="code">%global serverType jboss</code></p>
| + | |
| − | ;deployDir
| + | |
| − | :<p>the application server deployment directory (relative to <code class="varname">ADEMPIERE_HOME</code>)</p><p>default:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">jboss/server/adempiere/deploy</code> for JBoss</p></li><li><p><code class="constant">glassfish/glassfish/domains/domain1</code> for Glassfish</p></li></ul></div><p>
| + | |
| − | </p><p>example: <code class="code">%global deployDir jboss/server/adempiere/deploy</code></p>
| + | |
| − | ;jnpPort
| + | |
| − | :<p>the JNP port (whatever that is)</p><p>default:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">1099</code> for JBoss</p></li><li><p><code class="constant">3700</code> for Glassfish</p></li></ul></div><p>
| + | |
| − | </p><p>example: <code class="code">%global jnpPort 1099</code></p>
| + | |
| − | ;webPort
| + | |
| − | :<p>the TCP port to be used by the application server for HTTP</p><p>default: <code class="constant">8888</code></p><p>example: <code class="code">%global webPort 8888</code></p>
| + | |
| − | ;sslPort
| + | |
| − | :<p>the TCP port to be used by the application server for HTTPS</p><p>default: <code class="constant">8443</code></p><p>example: <code class="code">%global sslPort 8443</code></p>
| + | |
| − | ;logFacility
| + | |
| − | :<p>which facility to use for the system logger</p><p>values: <code class="constant">local0</code> … <code class="constant">local7</code></p><p>default: <code class="constant">local1</code></p><p>example: <code class="code">%global logFacility local1</code></p>
| + | |
| − | ;logLevel
| + | |
| − | :<p>the minimum severity level for messages to be logged</p><p>values: <code class="constant">DEBUG</code>, <code class="constant">INFO</code>, <code class="constant">NOTICE</code>, <code class="constant">WARNING</code>, <code class="constant">ERROR</code>, <code class="constant">CRITICAL</code>, <code class="constant">ALERT</code>, <code class="constant">EMERGENCY</code></p><p>default: <code class="constant">INFO</code></p><p>example: <code class="code">%global logLevel INFO</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Database Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;dbServer
| + | |
| − | :<p>the name of the database server</p><p>default: name portion of <code class="varname">%{serverFQDN}</code> (assuming that <span class="productname">Adempiere</span> is installed on the same machine as the database)</p><p>example: <code class="code">%global dbServer myDatabaseServer</code></p>
| + | |
| − | ;dbType
| + | |
| − | :<p>the type of database (database vendor)</p><p>values: <code class="constant">oracle</code>, <code class="constant">oracleXE</code>, <code class="constant">postgresql</code></p><p>default: <code class="constant">postgresql</code></p><p>example: <code class="code">%global dbType postgresql</code></p>
| + | |
| − | ;dbPort
| + | |
| − | :<p>the database port</p><p>default:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">5432</code> for <span class="productname">PostgreSQL</span></p></li><li><p><code class="constant">1521</code> for <span class="productname">Oracle</span></p></li></ul></div><p>
| + | |
| − | </p><p>example: <code class="code">%global dbPort 1521</code></p>
| + | |
| − | ;dbName
| + | |
| − | :<p>the name of the database</p><p>default:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">adempiere</code> for <span class="productname">PostgreSQL</span></p></li><li><p><code class="constant">orcl</code> for <span class="productname">Oracle</span></p></li><li><p><code class="constant">xe</code> for <span class="productname">OracleXE</span></p></li></ul></div><p>
| + | |
| − | </p><p>example: <code class="code">%global dbName adempiere</code></p>
| + | |
| − | ;dbUrl
| + | |
| − | :<p>the url for the jdbc driver to connect to the database</p><p>default:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p>jdbc:postgresql://<code class="varname">%{dbServer}</code>:<code class="varname">%{dbPort}</code>/<code class="varname">%{dbName}</code> for <span class="productname">PostgreSQL</span></p></li><li><p>jdbc:oracle:thin:@//<code class="varname">%{dbServer}</code>:<code class="varname">%{dbPort}</code>/<code class="varname">%{dbName}</code> for <span class="productname">Oracle</span></p></li></ul></div><p>
| + | |
| − | </p><p>example: <code class="code">%global dbUrl jdbc:postgresql://myDatabaseServer:5432/adempiere</code></p>
| + | |
| − | ;dbUser
| + | |
| − | :<p>the name of the adempiere database user</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global dbUser adempiere</code></p>
| + | |
| − | ;dbPassword
| + | |
| − | :<p>the password of the adempiere database user</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global dbPassword adempiere</code></p>
| + | |
| − | ;dbSystemUser
| + | |
| − | :<p>the user name of the database system administrator</p><p>default:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">postgres</code> for <span class="productname">PostgreSQL</span></p></li><li><p><code class="constant">system</code> for <span class="productname">Oracle</span></p></li></ul></div><p>
| + | |
| − | </p><p>example: <code class="code">%global dbSystemUser postgres</code></p>
| + | |
| − | ;dbSystemPassword
| + | |
| − | :<p>the password of the database system administrator</p><p>default:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">postgres</code> for <span class="productname">PostgreSQL</span></p></li><li><p><code class="constant">manager</code> for <span class="productname">Oracle</span></p></li></ul></div><p>
| + | |
| − | </p><p>example: <code class="code">%global dbSystemPassword postgres</code></p>
| + | |
| − | ;oracleHome
| + | |
| − | :<p>When using Oracle, the adempiere user needs to have access to the Oracle client on the local machine.</p><p>This is the <code class="varname">ORACLE_HOME</code> environment variable pointing to the oracle product directory.</p><p>To keep the adempiere packages independent of the installed Oracle version, if the Oracle product directory contains a version in its name, it is recommended to create symbolic link from the Oracle product directory to a version-free name such as <code class="filename">/opt/oracle/oracle</code> at the time of Oracle installation.</p><p>This can be done with the command</p><div class="informalexample"><p><code class="prompt"># </code><span class="command"><strong>ln -s /opt/oracle/product/10.2.01 /opt/oracle/oracle</strong></span></p></div><p>default: <code class="constant">/opt/oracle/oracle</code></p><p>example: <code class="code">%global oracleHome /opt/oracle/product/10.2.01</code></p>
| + | |
| − | ;oracleTnsAdmin
| + | |
| − | :<p>When using Oracle, the adempiere user needs to have access to the Oracle client on the local machine.</p><p>This is the <code class="varname">TNS_ADMIN</code> environment variable pointing to the location where Oracle Net Services look for configuration files.</p><p>default: <code class="varname">%{oracleHome}</code>/network/admin</p><p>example: <code class="code">%global oracleTnsAdmin /opt/oracle/product/10.2.01/network/admin</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===FTP Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;ftpServer
| + | |
| − | :<p>name of the FTP server</p><p>default: name portion of <code class="varname">%{serverFQDN}</code></p><p>example: <code class="code">%global ftpServer myAppServer</code></p>
| + | |
| − | ;ftpPrefix
| + | |
| − | :<p>the FTP prefix to use</p><p>(no idea what this does)</p><p>default: <code class="constant">my</code></p><p>example: <code class="code">%global ftpPrefix my</code></p>
| + | |
| − | ;ftpUser
| + | |
| − | :<p>the FTP user</p><p>default: <code class="constant">anonymous</code></p><p>example: <code class="code">%global ftpUser anonymous</code></p>
| + | |
| − | ;ftpPassword
| + | |
| − | :<p>the FTP user's password</p><p>default: <code class="constant">user@host.com</code></p><p>example: <code class="code">%global ftpPassword user@host.com</code></p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===E-Mail Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;mailServer
| + | |
| − | :<p>the mail server to use</p><p>default: mailserver.(domain portion of <code class="varname">%{serverFQDN}</code>)</p><p>example: <code class="code">%global mailServer mailserver.mydomain.com</code></p>
| + | |
| − | ;mailAddress
| + | |
| − | :<p>the default administrative mail address to use</p><p>It can be overwritten on client level</p><p>default: adempiere@(domain portion of <code class="varname">%{serverFQDN}</code>)</p><p>example: <code class="code">%global mailAddress adempiere@mydomain.com</code></p>
| + | |
| − | ;mailUser
| + | |
| − | :<p>the user of the default mail account</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global mailUser adempiere</code></p>
| + | |
| − | ;mailPassword
| + | |
| − | :<p>the password of the default mail account</p><p>default: <code class="constant">adempiere</code></p><p>example: <code class="code">%global mailPassword adempiere</code></p></dl></div></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Corporate Format Settings==
| + | |
| − | </div></div></div><p>
| + | |
| − | Some sites may want to enforce their own corporate formats, i.e. no matter what locale the user is working in or what
| + | |
| − | language a business partner has defined, always the same decimal point, date format, and paper size are used, regardless
| + | |
| − | of what the locale conventions are.
| + | |
| − | </p><p>
| + | |
| − | (And the locale conventions are often wrong in Java, anyway).
| + | |
| − | </p><p>
| + | |
| − | This is technically a patch, but as the target file may change frequently, it would be very cumbersome to always keep the
| + | |
| − | patch file up to date.
| + | |
| − | </p><p>
| + | |
| − | It has therefore been incorporated as a script in the %prep section.
| + | |
| − | </p><div><dl>
| + | |
| − | ;useCorporateFormat
| + | |
| − | :<p>whether to apply the corporate format patch</p><p>Note that this changes the locale conventions for the complete installation and thus affects all clients.</p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">0</code> = do not use corporate formats</p></li><li><p><code class="constant">1</code> = use corporate formats</p></li></ul></div><p>
| + | |
| − | </p><p>default: <code class="constant">0</code></p><p>example: <code class="code">%global useCorporateFormat 0</code></p>
| + | |
| − | ;formatDecimal
| + | |
| − | :<p>whether to use a point as decimal separator</p><p>values:
| + | |
| − | </p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">0</code> = use a comma as decimal separator</p></li><li><p><code class="constant">1</code> = use a point as decimal separator</p></li></ul></div><p>
| + | |
| − | </p><p>default: <code class="constant">1</code></p><p>example: <code class="code">%global formatDecimal 1</code></p>
| + | |
| − | ;formatDate
| + | |
| − | :<p>the date format to use</p><p>
| + | |
| − | The formats are probably described somewhere in Java documentation.
| + | |
| − | Have a look at looks/src/org/compiere/util/Language.java for examples.
| + | |
| − | </p><p>default: <code class="constant">yyyy-MM-dd</code></p><p>example: <code class="code">%global formatDate yyyy-MM-dd</code></p>
| + | |
| − | ;formatPaper
| + | |
| − | :<p>the paper size to use.</p><p>
| + | |
| − | The formats are probably described somewhere in Java documentation.
| + | |
| − | Have a look at looks/src/org/compiere/util/Language.java for examples.
| + | |
| − | </p><p>values: <code class="constant">ISO.A4</code>, <code class="constant">NA.LETTER</code></p><p>default: <code class="constant">ISO.A4</code></p><p>example: <code class="code">%global formatPaper ISO.A4</code></p></dl></div></div></div>
| + | |
| | [[Category:Developer documentation]] | | [[Category:Developer documentation]] |
| | [[Category:Projects and Tools]] | | [[Category:Projects and Tools]] |
