Difference between revisions of "Simple Package Modification"

From SME Server
Jump to navigationJump to search
(Update CVS server details)
 
(68 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{Level|Developer}}
 
The simplest package modification is for someone to access the code via anonymous CVS and produce a patch to put into Bugzilla.
 
The simplest package modification is for someone to access the code via anonymous CVS and produce a patch to put into Bugzilla.
 
This can be done on SME 8 by installing only cvs as follows.
 
This can be done on SME 8 by installing only cvs as follows.
  
 +
== Setting up your build server ==
 +
This How-to is based on SME8, and that you have your development SME8 server fully updated and up and running. This can be a dedicated machine or a virtual machine.
  
Using SME 8
+
==== Install CVS ====
 +
SME Server uses CVS for maintaining code and packages. By default, CVS is not installed on SME8 (not required for normal SME Server operation). To install CVS on SME8 issue the following command as root user.
 +
yum install cvs
  
Create a new user, eg builder
+
==== Create a new 'builder' user ====
 +
We will create a new user account that we use for our building purposes. The new user account can be created, as usual, through the server-manager, In this How-To we will have named our new user account 'builder'
  
 +
useradd builder
 +
passwd builder
  
You will need to alter your user account to enable regular login. If you want to enable account "builder", then you would type the following commands from the root account:
+
==== Grant shell access ====
 +
The 'builder' account needs to be able to login and have shell access. For this you will need to grant permissions. Type the following commands from the root account:
 +
chsh -s /bin/bash builder
 +
db accounts setprop builder Shell /bin/bash
  
chsh -s /bin/bash builder
+
After issuing the above commands, the user 'builder' should be able to login on the console. Please login as user 'builder', for the the rest of the instructions assume you are loged in as user 'builder'
db accounts setprop builder Shell /bin/bash
 
  
Install CVS
+
==== Create a development directory ====
 +
The user 'builder needs a dedicated development directory. In this How-To we will use ~/home/smeserver. To create the directory ~/home/smeserver please issue the following command as user 'builder':
 +
mkdir ~/smeserver
 +
cd ~/smeserver
  
yum install cvs
+
To add the smecontribs cvs:
 +
mkdir ~/smecontribs
 +
cd ~/smecontribs
  
create a development directory, eg ~/home/smeserver
+
This is all what is required to setup your server to be able to start working on patches and packages.
  
mkdir ~/home/smeserver
+
== Retrieve code ==
cd ~/home/smeserver
+
==== Getting the source code ====
 +
In this How-To we want to work on the package 'e-smith-base'. We first need to download (with CVS this is called retrieving) the code for 'e-smith-base' from the SME Server CVS repository at koozali.org, we can also retrieve the CVS for the smecontribs tree. For this issue the following commands:
 +
cd ~/smeserver
 +
cvs -z3 -d:pserver:anonymous@shell.koozali.org:/cvs/smeserver checkout -P e-smith-base
  
Download the module you want to work on, eg e-smith-base
+
For the 'smeserver-base' base from the contribs tree.
 +
cd ~/smecontribs
 +
cvs -z3 -d:pserver:anonymous@shell.koozali.org:/cvs/smecontribs checkout -P smeserver-base
  
cvs -z3 -d:pserver:anonymous@smeserver.cvs.sourceforge.net:/cvsroot/smeserver checkout -P e-smith-base
+
Next to a selective retrieve as per above, you can also retrieve the whole CVS tree.
 +
cd ~/smeserver
 +
cvs -z3 -d:pserver:anonymous@shell.koozali.org:/cvs/smeserver co -P rpms
  
Alternatively retrieve the whole CVS tree
+
For the SME contribs tree.
# cd ~/home/smeserver
+
cd ~/smecontribs
# cvs -z3 -d:pserver:anonymous@smeserver.cvs.sourceforge.net:/cvsroot/smeserver co -P rpms  
+
cvs -z3 -d:pserver:anonymous@shell.koozali.org:/cvs/smecontribs co -P rpms  
  
You can now retrieve one of the packages from SourceForge. In this case, we want to modify the e-smith-base package for SME8, so let's retrieve it from SourceForge:
+
If you want to update/refresh the whole CVS tree smeserver or smecontribs, run the following from the rpms directory, or any lower directory with a CVS dir , issue
 +
cvs update -dPA
  
Change to work directory
+
To work on the e-smith-base smeserver tree, change to the e-smith-base SME8 directory:
 +
cd ~/smeserver/rpms/e-smith-base/sme8
  
cd ~/home/smeserver/rpms/e-smith-base/sme8
+
Then we have to prepare a tree. Issue the following commands:
 +
cvs update -dPA
 +
make clean
 +
make prep
 +
Please ignore if 'make clean' returns an error about a missing *.tgz package
  
To prepare a tree
+
Our patch will be a done with the 'diff' tool which compares the edited files against the original files. So we need to to save a copy of the original files:
 +
cp -R e-smith-base-5.2.0 e-smith-base-5.2.0.old
  
cvs  update -dPA
+
== Make changes ==
make clean       
+
==== Edit the source code ====
make prep
+
Now we can make the changes or edit the source code in e-smith-base-5.2.0.
  
Save a copy of the original files
+
For a simple test you can edit the SME8 'e-smith-base-5.2.0/root/sbin/e-smith/console' file and add something to the header.
cp -R e-smith-base-5.2.0 e-smith-base-5.2.0.old
 
  
<Now make the changes needed to the files in e-smith-base-5.2.0>
+
cd ~/smeserver/rpms/e-smith-base/sme8
 +
nano -w e-smith-base-5.2.0/root/sbin/e-smith/console
  
Create a patch
+
<pre>
diff -urN smeserver-foo-2.0.0.old smeserver-yum-2.0.0 > smeserver-yum-2.0.0-importKeys.patch
+
#!/usr/bin/perl -w
  
 +
#----------------------------------------------------------------------
 +
# copyright (C) 1999-2006 Mitel Corporation
 +
#
 +
# 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.
 +
#
 +
# 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.
 +
#
 +
# 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
 +
#
 +
# Let's see if this new line pops up in my patch file and my new test RPM !!!    <----- Add this line
 +
#----------------------------------------------------------------------
 +
</pre>
 +
Save the file
  
Now to make a build to test if it works:
+
== Create a patch ==
 +
When we have finished our editing of the source code (see above example), we can create a patch. (a file that contains the differences between the original file and the file we have been working on). To create the patch issue the following command:
 +
 +
cd ~/smeserver/rpms/e-smith-base/sme8
 +
diff -urN e-smith-base-5.2.0.old e-smith-base-5.2.0 > e-smith-base-5.2.0-test.patch
  
Update the spec file
+
==== Test the patch ====
#increase the release
+
To see if our changes work correctly as intended, we will make a local RPM build to test, and before building the RPM it is necessary to update the spec file to increase the release number and to ensure your patch is included in the build.
%define release 15
 
  
#add the patch
+
===== Update the spec file =====
Patch2: smeserver-foo-1.2-widget.patch
+
First we will update the spec file. Spec files are text files that contain RPM directives and macro definitions, which are used to build an RPM package.
  
#update the changelog, include the bug number
+
For our examle we will continue to use the e-smith-base-5.2.0
* Fri Jan 11 2008 John Smith <smith@foo.net> 1.2-15
 
- fixed foo to create bar [SME 3470]
 
  
#apply the patch in %setup
+
cd ~/smeserver/rpms/e-smith-base/sme8
%patch2 -p1
 
  
 +
Edit the file e-smith-base.spec
  
CHECK: that the changelog version really matches the RPM version.
+
nano e-smith-base.spec
  
CHECK: Is the spec file correct, look at the changes
+
and change:
cvs diff e-smith-base.spec
 
  Have you updated the release? Is that new release in the changelog?
 
  Have you included the patch, Patch1: e-smith-proftpd-2.2.0-persistent_passwd.patch
 
  Is the changelog correct
 
* Tue Jan 22 2013 Ian Wells <esmith@wellsi.com> 2.2.0-4.sme
 
- Remove previous change [SME: 7129]
 
    There must be a bugzilla number in this format [SME: 7129]
 
    Is the date really correct? Both day and date.
 
    The version should follow after the email address
 
  
CHECK: what would be committed
+
<pre>
cvs update
+
#increase the release version at the beginning of the spec file
    * M modified, will be committed
+
%define release 68
    * U file has been updated since you last checked it out
 
    * A added, will be added on commit
 
    * D deleted, will be deleted on commit
 
    * ? egregious file not part of CVS record for this dir
 
  
CHECK: has the patch files been added? cvs add e-smith-quota-2.0.0-badlyformattedie8.patch
+
#add the patch to the existing patchlist section:
CHECK: are the files UNIX or do they have DOS endings (bad)
+
Patch2: e-smith-base-5.2.0-test.patch
  
Build the rpm locally to test, (note, this deletes the working tree!)
+
#update the changelog section, including the release version and bug number
make local
+
* Wed Jan 23 2013 John Doe <jdoe@foo.net> 5.2.0-68.sme
 +
- just a test to see if I can do this [SME: 7129]
  
 +
#add patch version to the %setup section
 +
%patch2 -p1
 +
</pre>
  
Once the patch works, attach the patch to the bugzilla entry.
+
Save the file
  
 +
To check the changes issue the following command which compares your updated spec file with the original one in CVS. This is an optional step, but helps catch errors in the spec file.
  
--- this simple package modification ends here ---
+
cvs diff -u e-smith-base.spec
  
*** If you have CVS access then ***
+
* Ensure that the changelog version really matches the RPM version.
 +
* Check if the spec file correct, look at the changes
 +
* There must be a bugzilla number in this format [SME: 7129]
 +
* Is the date really correct? Both day and date.
 +
* The version should follow after the email address
  
Once you are satisfied and want to submit the package to the build server commit your changes. (Please use descriptive comments so that other developers are aware of what is happening. Comments will appear on the subject line of the commit email that get send to the other developers.)
+
==== Build the test RPM ====
cvs commit -m 'your descriptive commit message here'
+
Build the rpm locally to test, (note, this deletes the working tree!<-- Please explain)
cvs commit -m ''  <-- copy this then add changelog line
+
make local
  
*** If you have build access then ***
+
A new RPM e-smith-base-5.2.0-68.el5.sme.x86_64.rpm will be created which you can test or explore to see if your changes are applied
  
Then build it (from either the sme7 or sme8 dir):
+
Once the patch works, attach the patch to the bugzilla entry. That is all what it takes to create a patch.
 +
You can also, optionally, attach the updated spec file.
  
make tag
+
This simple package modification ends here. The next section is intended for developers who have CVS commit and build access. The developers will also check your patches and apply them to the CVS tree for you.
make build
+
 
 +
== Committing the patch ==
 +
==== If you have CVS commit access ====
 +
 
 +
CVS needs to be updated. To check what will be committed to CVS, issue the following command:
 +
cvs update
 +
 
 +
* M modified, will be committed
 +
* U file has been updated since you last checked it out
 +
* A added, will be added on commit
 +
* D deleted, will be deleted on commit
 +
* ? egregious file not part of CVS record for this dir
 +
 
 +
* Ensure that the patch file has been added
 +
cvs add e-smith-base-5.2.0-test.patch
 +
* Ensure that your patch/files etc. are UNIX style and do not have DOS endings.
 +
 
 +
Once you are satisfied and want to submit the package to CVS commit your changes. (Please use descriptive comments so that other developers are aware of what is happening. Comments will appear on the subject line of the commit email that get send to the other developers.):
 +
cvs commit -m 'your descriptive commit message here'
 +
 
 +
for example
 +
cvs commit -m '* Wed Jan 23 2013 John Doe <jdoe@foo.net> 5.2.0-68.sme
 +
- just a test to see if I can do this [SME: 7129]'
 +
 
 +
==== If you have build access ====
 +
Build it (from either the sme7 or sme8 dir):
 +
make tag
 +
make build
 +
[[Category:SME9-Development]]
 +
[[Category:SME Server Development Framework]]
 +
[[Category:Development Tools]]

Latest revision as of 05:17, 18 November 2017

PythonIcon.png Skill level: Developer
Risk of inconsistencies with Koozali SME Server methodology, upgrades & functionality is high. One must be knowledgeable about how changes impact their Koozali SME Server. Significant risk of irreversible harm.


The simplest package modification is for someone to access the code via anonymous CVS and produce a patch to put into Bugzilla. This can be done on SME 8 by installing only cvs as follows.

Setting up your build server

This How-to is based on SME8, and that you have your development SME8 server fully updated and up and running. This can be a dedicated machine or a virtual machine.

Install CVS

SME Server uses CVS for maintaining code and packages. By default, CVS is not installed on SME8 (not required for normal SME Server operation). To install CVS on SME8 issue the following command as root user.

yum install cvs

Create a new 'builder' user

We will create a new user account that we use for our building purposes. The new user account can be created, as usual, through the server-manager, In this How-To we will have named our new user account 'builder'

useradd builder
passwd builder

Grant shell access

The 'builder' account needs to be able to login and have shell access. For this you will need to grant permissions. Type the following commands from the root account:

chsh -s /bin/bash builder
db accounts setprop builder Shell /bin/bash

After issuing the above commands, the user 'builder' should be able to login on the console. Please login as user 'builder', for the the rest of the instructions assume you are loged in as user 'builder'

Create a development directory

The user 'builder needs a dedicated development directory. In this How-To we will use ~/home/smeserver. To create the directory ~/home/smeserver please issue the following command as user 'builder':

mkdir ~/smeserver
cd ~/smeserver

To add the smecontribs cvs:

mkdir ~/smecontribs
cd ~/smecontribs 

This is all what is required to setup your server to be able to start working on patches and packages.

Retrieve code

Getting the source code

In this How-To we want to work on the package 'e-smith-base'. We first need to download (with CVS this is called retrieving) the code for 'e-smith-base' from the SME Server CVS repository at koozali.org, we can also retrieve the CVS for the smecontribs tree. For this issue the following commands:

cd ~/smeserver
cvs -z3 -d:pserver:anonymous@shell.koozali.org:/cvs/smeserver checkout -P e-smith-base

For the 'smeserver-base' base from the contribs tree.

cd ~/smecontribs
cvs -z3 -d:pserver:anonymous@shell.koozali.org:/cvs/smecontribs checkout -P smeserver-base

Next to a selective retrieve as per above, you can also retrieve the whole CVS tree.

cd ~/smeserver
cvs -z3 -d:pserver:anonymous@shell.koozali.org:/cvs/smeserver co -P rpms 

For the SME contribs tree.

cd ~/smecontribs
cvs -z3 -d:pserver:anonymous@shell.koozali.org:/cvs/smecontribs co -P rpms 

If you want to update/refresh the whole CVS tree smeserver or smecontribs, run the following from the rpms directory, or any lower directory with a CVS dir , issue

cvs update -dPA

To work on the e-smith-base smeserver tree, change to the e-smith-base SME8 directory:

cd ~/smeserver/rpms/e-smith-base/sme8

Then we have to prepare a tree. Issue the following commands:

cvs update -dPA
make clean
make prep

Please ignore if 'make clean' returns an error about a missing *.tgz package

Our patch will be a done with the 'diff' tool which compares the edited files against the original files. So we need to to save a copy of the original files:

cp -R e-smith-base-5.2.0 e-smith-base-5.2.0.old

Make changes

Edit the source code

Now we can make the changes or edit the source code in e-smith-base-5.2.0.

For a simple test you can edit the SME8 'e-smith-base-5.2.0/root/sbin/e-smith/console' file and add something to the header.

cd ~/smeserver/rpms/e-smith-base/sme8
nano -w e-smith-base-5.2.0/root/sbin/e-smith/console
#!/usr/bin/perl -w

#----------------------------------------------------------------------
# copyright (C) 1999-2006 Mitel Corporation
#
# 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.
#
# 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.
#
# 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
#
# Let's see if this new line pops up in my patch file and my new test RPM !!!     <----- Add this line
#----------------------------------------------------------------------

Save the file

Create a patch

When we have finished our editing of the source code (see above example), we can create a patch. (a file that contains the differences between the original file and the file we have been working on). To create the patch issue the following command:

cd ~/smeserver/rpms/e-smith-base/sme8 
diff -urN e-smith-base-5.2.0.old e-smith-base-5.2.0 > e-smith-base-5.2.0-test.patch

Test the patch

To see if our changes work correctly as intended, we will make a local RPM build to test, and before building the RPM it is necessary to update the spec file to increase the release number and to ensure your patch is included in the build.

Update the spec file

First we will update the spec file. Spec files are text files that contain RPM directives and macro definitions, which are used to build an RPM package.

For our examle we will continue to use the e-smith-base-5.2.0

cd ~/smeserver/rpms/e-smith-base/sme8

Edit the file e-smith-base.spec

nano e-smith-base.spec

and change:

 #increase the release version at the beginning of the spec file
 %define release 68

 #add the patch to the existing patchlist section:
 Patch2: e-smith-base-5.2.0-test.patch

 #update the changelog section, including the release version and bug number
 * Wed Jan 23 2013 John Doe <jdoe@foo.net> 5.2.0-68.sme
 - just a test to see if I can do this [SME: 7129]

 #add patch version to the %setup section
 %patch2 -p1

Save the file

To check the changes issue the following command which compares your updated spec file with the original one in CVS. This is an optional step, but helps catch errors in the spec file.

cvs diff -u e-smith-base.spec
  • Ensure that the changelog version really matches the RPM version.
  • Check if the spec file correct, look at the changes
  • There must be a bugzilla number in this format [SME: 7129]
  • Is the date really correct? Both day and date.
  • The version should follow after the email address

Build the test RPM

Build the rpm locally to test, (note, this deletes the working tree!<-- Please explain)

make local

A new RPM e-smith-base-5.2.0-68.el5.sme.x86_64.rpm will be created which you can test or explore to see if your changes are applied

Once the patch works, attach the patch to the bugzilla entry. That is all what it takes to create a patch. You can also, optionally, attach the updated spec file.

This simple package modification ends here. The next section is intended for developers who have CVS commit and build access. The developers will also check your patches and apply them to the CVS tree for you.

Committing the patch

If you have CVS commit access

CVS needs to be updated. To check what will be committed to CVS, issue the following command:

cvs update
* M modified, will be committed
* U file has been updated since you last checked it out
* A added, will be added on commit
* D deleted, will be deleted on commit
* ? egregious file not part of CVS record for this dir
  • Ensure that the patch file has been added
cvs add e-smith-base-5.2.0-test.patch
  • Ensure that your patch/files etc. are UNIX style and do not have DOS endings.

Once you are satisfied and want to submit the package to CVS commit your changes. (Please use descriptive comments so that other developers are aware of what is happening. Comments will appear on the subject line of the commit email that get send to the other developers.):

cvs commit -m 'your descriptive commit message here'

for example

cvs commit -m '* Wed Jan 23 2013 John Doe <jdoe@foo.net> 5.2.0-68.sme
- just a test to see if I can do this [SME: 7129]'

If you have build access

Build it (from either the sme7 or sme8 dir):

make tag
make build