Changes

<div class="CHAPTER">

<div class="CHAPTER">

=Packaging your application=

==Packaging your application==

Once you have created a customization for your SME Server by adding new files, directories, and symbolic links (for your actions, events, etc.) - and perhaps also triggering an action to initialize your customization - you are ready to package your customization into an RPM.

Once you have created a customization for your SME Server by adding new files, directories, and symbolic links (for your actions, events, etc.) - and perhaps also triggering an action to initialize your customization - you are ready to package your customization into an RPM.

----

----

==A quick introduction to RPMs==

===A quick introduction to RPMs===

All SME Server software packages are distributed as RPM packages. This is the format used by CentOS and other major Linux distributions for distributing applications and other collections of files. The RPM system provides the ability to install, upgrade, remove and (importantly) verify the contents of installed packages.

All SME Server software packages are distributed as RPM packages. This is the format used by CentOS and other major Linux distributions for distributing applications and other collections of files. The RPM system provides the ability to install, upgrade, remove and (importantly) verify the contents of installed packages.

----

----

==Selecting and creating RPMs for your application==

===Selecting and creating RPMs for your application===

Your application will typically depend on several components:

Your application will typically depend on several components:

----

----

==Setting up your RPM development environment==

===Setting up your RPM development environment===

 

If you haven't done so already, set up an RPM development environment. If you are using an SME Server as your development environment, you will need to alter your user account to enable regular login. If you want to enable account "joe", then you would type the following commands from the root account:

If you haven't done so already, set up an RPM development environment. If you are using an SME Server as your development environment, you will need to alter your user account to enable regular login. If you want to enable account "joe", then you would type the following commands from the root account:

   

   

  db accounts setprop joe Shell /bin/bash

  db accounts setprop joe Shell /bin/bash

 

{{Note box|msg=Shell/login access is disabled by default to enhance the security of the SME Server. Shell access should only be provided to users who require it and who can be trusted to maintain system security.}}

<div class="NOTE"><blockquote class="NOTE">

 

'''Note: '''Shell/login access is disabled by default to enhance the security of the SME Server. Shell access should only be provided to users who require it and who can be trusted to maintain system security.

 

Then you should be able to log in to the server as user "joe", and get a Linux command line prompt. Log in, then type the following commands to set up your RPM work area:

Then you should be able to log in to the server as user "joe", and get a Linux command line prompt. Log in, then type the following commands to set up your RPM work area:

----

----

==Building an RPM==

===Building an RPM===

This section describes the process for building an RPM - step by step.

 

Collect all of the files which have been created in the previous sections into the <tt class="FILENAME">/tmp/</tt> directory. There is one additional file <tt class="FILENAME">createlinks</tt> which looks like this:

#!/usr/bin/perl -w

# Collect all of the files which have been created in the previous sections into the <tt class="FILENAME">/tmp/</tt> directory. There is one additional file <tt class="FILENAME">createlinks</tt> which looks like this: <nowiki>#!/usr/bin/perl -w

   

   

  use esmith::Build::CreateLinks qw(:all);

  use esmith::Build::CreateLinks qw(:all);

  panel_link("loggerdemo", $panel);

  panel_link("loggerdemo", $panel);

   

   

Create the directory hierarchy required for building the RPM. This is very close to the hierarchy on the installed system.  

# Create the directory hierarchy required for building the RPM. This is very close to the hierarchy on the installed system. <nowiki># Change to the SOURCES directory

 

# Change to the SOURCES directory

  cd ~/rpms/SOURCES

  cd ~/rpms/SOURCES

   

   

   

   

  # The createlinks auxiliary file

  # The createlinks auxiliary file

  cp -p /tmp/createlinks .</nowiki>Your directory structure should now look like this: [gordonr@sevendev1 loggerdemo-1.0.0]$ find . -type f

  cp -p /tmp/createlinks .

mkdir -p root/etc/e-smith/db/configuration/defaults/loggerdemo

echo "service"  > !$/type

Your directory structure should now look like this:  

 

[gordonr@sevendev1 loggerdemo-1.0.0]$ find . -type f

  ./root/etc/e-smith/templates/etc/crontab/25templatedemo

  ./root/etc/e-smith/templates/etc/crontab/25templatedemo

  ./root/etc/e-smith/locale/en-us/etc/e-smith/web/functions/loggerdemo

  ./root/etc/e-smith/locale/en-us/etc/e-smith/web/functions/loggerdemo

  ./root/etc/e-smith/web/functions/loggerdemo

  ./root/etc/e-smith/web/functions/loggerdemo

  ./root/usr/lib/perl5/site_perl/esmith/FormMagick/Panel/loggerdemo.pm

  ./root/usr/lib/perl5/site_perl/esmith/FormMagick/Panel/loggerdemo.pm

  ./createlinks

  ./createlinks

# Package the directory into a tarball: cd ~/rpms/SOURCES

 

Package the directory into a tarball: cd ~/rpms/SOURCES

  tar zcvf loggerdemo-1.0.0.tar.gz loggerdemo-1.0.0

  tar zcvf loggerdemo-1.0.0.tar.gz loggerdemo-1.0.0

# Create the RPM specification "SPEC" file <tt class="FILENAME">~/rpms/SPECS/loggerdemo.spec</tt> which looks like this: <nowiki>

 

%define name loggerdemo

Create the RPM specification "SPEC" file <tt class="FILENAME">~/rpms/SPECS/loggerdemo.spec</tt> which looks like this:  

 

%define name loggerdemo

  %define version 1.0.0

  %define version 1.0.0

  %define release 01

  %define release 01

  %build

  %build

  perl createlinks

  perl createlinks

   

   

  %install

  %install

   

   

  %post

  %post

  /sbin/e-smith/expand-template /etc/crontab

  /sbin/e-smith/expand-template /etc/crontab

  true

  true

  %defattr(-,root,root)

  %defattr(-,root,root)

   

   

</nowiki>Note the <var class="LITERAL">%post</var> (post-installation) and <var class="LITERAL">%postun</var> (post-uninstallation) statements which expand the <tt class="FILENAME">/etc/crontab</tt> template after installing or uninstalling the RPM.

 

# Check that your RPM will build OK with "build prepare": cd ~/rpms/SPECS

Note the <var class="LITERAL">%post</var> (post-installation) and <var class="LITERAL">%postun</var> (post-uninstallation) statements which expand the <tt class="FILENAME">/etc/crontab</tt> template after installing or uninstalling the RPM.

  rpmbuild -bp loggerdemo.specThe last line of output should be <var class="LITERAL">+ exit 0</var> if rpmbuild is successful.

 

# Run the '''rpmbuild''' command again to actually create your RPM with the "build all" options: rpmbuild -ba loggerdemo.specIf everything was successful, the last line of output should again be <var class="LITERAL">+ exit 0</var>.

Check that your RPM will build OK with "build prepare":  

# The RPMs should have been generated and put into <tt class="FILENAME">~/rpms/RPMS/noarch/</tt> as this program can run equally well on any platform. A source RPM should also exist in <tt class="FILENAME">~/rpms/SRPMS/</tt>.

cd ~/rpms/SPECS

# Test your RPM by installing it on an SME Server test box.<div class="NOTE"><blockquote class="NOTE">'''Note: '''RPMs need to be installed as <var class="LITERAL">root</var>, but you should not log in as the root user. Instead, you should create a normal user and provide them with 'root' privileges via the '''sudo''' command. To provide full <span class="emphasis">''sudo''</span> rights to the user <var class="LITERAL">joe</var>, use the '''su - -c /usr/sbin/visudo''' and add the following line to the end of the file: joe    ALL=(ALL) ALLYou can then use the '''sudo''' to run commands as <var class="LITERAL">root</var> when required. You will be prompted for your password (not the root password) which ensures that someone else isn't using your terminal.</blockquote></div> [joe@sevendev1 SPECS]$ sudo rpm -Uvh \

  rpmbuild -bp loggerdemo.spec

    ~/rpms/RPMS/noarch/loggerdemo-1.0.0-01.noarch.rpm

The last line of output should be <var class="LITERAL">+ exit 0</var> if rpmbuild is successful.

 

Run the '''rpmbuild''' command again to actually create your RPM with the "build all" options:

rpmbuild -ba loggerdemo.spec

 

If everything was successful, the last line of output should again be <var class="LITERAL">+ exit 0</var>.

 

The RPMs should have been generated and put into <tt class="FILENAME">~/rpms/RPMS/noarch/</tt> as this program can run equally well on any platform. A source RPM should also exist in <tt class="FILENAME">~/rpms/SRPMS/</tt>.

 

Test your RPM by installing it on an SME Server test box.

{{Note box|msg=RPMs need to be installed as <var class="LITERAL">root</var>, but you should not log in as the root user. Instead, you should create a normal user and provide them with 'root' privileges via the '''sudo''' command. To provide full <span class="emphasis">''sudo''</span> rights to the user <var class="LITERAL">joe</var>, use the '''su - -c /usr/sbin/visudo''' and add the following line to the end of the file: joe    ALL=(ALL) ALLYou can then use the '''sudo''' to run commands as <var class="LITERAL">root</var> when required. You will be prompted for your password (not the root password) which ensures that someone else isn't using your terminal.}}

 

sudo yum localinstall  ~/rpms/RPMS/noarch/loggerdemo-1.0.0-01.noarch.rpm

  Preparing...                ########################################### [100%]

  Preparing...                ########################################### [100%]

     1:loggerdemo            ########################################### [100%]

     1:loggerdemo            ########################################### [100%]

  Migrating existing database backups

  Migrating existing database backups

  Migrating existing database yum_available

  Migrating existing database yum_available

  Migrating existing database domains<div class="NOTE"><blockquote class="NOTE">'''Note: '''In almost all instances you should use the <var class="LITERAL">-U</var> (upgrade) option to rpm instead of the <var class="LITERAL">-i</var> (install) option. The <var class="LITERAL">-i</var> option should be reserved for special operations, such as installing kernels.</blockquote></div>The customization should be fully installed, and the <tt class="FILENAME">/etc/crontab</tt> file should show the customization. Then remove the customization: <nowiki># remove the RPM

  Migrating existing database domains

  sudo rpm -e loggerdemo</nowiki>The customization should be completely gone, and the <tt class="FILENAME">/etc/crontab</tt> file should look the way it did before.

 

The customization should be fully installed, and the <tt class="FILENAME">/etc/crontab</tt> file should show the customization.  

 

Then remove the customization:  

  sudo rpm -e loggerdemo

 

The customization should be completely gone, and the <tt class="FILENAME">/etc/crontab</tt> file should look the way it did before.

<div class="SECT2">

<div class="SECT2">

----

----

===The createlinks script===

====The createlinks script====

The source tarballs of an RPM should not include symbolic links as they are difficult to store under many version control systems and cause issues when generating patches. Since the SME Server uses many symbolic links, there are simple methods for creating the ones required. This is done through the '''createlinks''' script which is called from the <var class="LITERAL">%build</var> section of the SPEC file. Let's examine one. It starts with the standard Perl script header and an import of the required module:

The source tarballs of an RPM should not include symbolic links as they are difficult to store under many version control systems and cause issues when generating patches. Since the SME Server uses many symbolic links, there are simple methods for creating the ones required. This is done through the '''createlinks''' script which is called from the <var class="LITERAL">%build</var> section of the SPEC file. Let's examine one. It starts with the standard Perl script header and an import of the required module: