2,411
edits
Changes
Jump to navigation
Jump to search
mLine 1:
Line 1: − + − + Line 11:
Line 11: − + Line 18:
Line 18: − + Line 25:
Line 25: − + Line 52:
Line 52: − + Line 73:
Line 73: − + Line 86:
Line 86: − + Line 106:
Line 106: − + Line 125:
Line 125: − + Line 156:
Line 156: − + Line 179:
Line 179: − + Line 205:
Line 205: − + Line 236:
Line 236: − + Line 246:
Line 246: − + Line 267:
Line 267: − + Line 320:
Line 320: − + Line 327:
Line 327: − + Line 347:
Line 347: − + Line 363:
Line 363: − + Line 385:
Line 385: − + Line 406:
Line 406: − + Line 442:
Line 442: − + Line 455:
Line 455: − + Line 466:
Line 466: − + Line 475:
Line 475: − + Line 484:
Line 484: − + Line 495:
Line 495: − + Line 508:
Line 508: − + Line 517:
Line 517: − + Line 524:
Line 524: − + Line 531:
Line 531: − + − + − − =IV. Advanced customization of the SME Server= − − <div class="TOC"> − − ; '''Table of Contents''' − ; 15. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#ADVANCED-CUSTOMIZATION Advanced customization principles] − −
SME Server:Documentation:Developers Manual:Chapter14 (view source)
Revision as of 13:48, 25 April 2008
, 13:48, 25 April 2008Adjusting header(s)
<div class="CHAPTER">
<div class="CHAPTER">
=The SME Server development environment=
==The SME Server development environment==
<div class="SECT1">
<div class="SECT1">
==Configuring your development environment==
===Configuring your development environment===
The SME Server source code is checked into CVS at SourceForge. The project has a SourceForge page at https://sourceforge.net/projects/smeserver/. All packages are built using '''mezzanine''', and an overview of mezzanine is provided here: https://wiki.caosity.org/tiki-index.php?page=Package+Maintenance
The SME Server source code is checked into CVS at SourceForge. The project has a SourceForge page at https://sourceforge.net/projects/smeserver/. All packages are built using '''mezzanine''', and an overview of mezzanine is provided here: https://wiki.caosity.org/tiki-index.php?page=Package+Maintenance
----
----
===Reminder: The SME Server is released under the GPL===
====Reminder: The SME Server is released under the GPL====
The SME Server source code is released under the GPL. You must release the source code to all modifications. If you make improvements, please raise a bug and attach a patch so the change can be discussed and pulled back into the base for everyone to share.
The SME Server source code is released under the GPL. You must release the source code to all modifications. If you make improvements, please raise a bug and attach a patch so the change can be discussed and pulled back into the base for everyone to share.
----
----
===Do I need a SourceForge account?===
====Do I need a SourceForge account?====
Not really. Only developers who are going to put patches back into CVS and build new packages need SourceForge CVS access. The sources are freely available and patches are gratefully received. Just follow the instructions in this section and attach the patch(es) to the Bugzilla entry, explaining why the change should be made.
Not really. Only developers who are going to put patches back into CVS and build new packages need SourceForge CVS access. The sources are freely available and patches are gratefully received. Just follow the instructions in this section and attach the patch(es) to the Bugzilla entry, explaining why the change should be made.
----
----
===Add some useful aliases===
====Add some useful aliases====
Mezzanine needs to know to use the SourceForge CVS repository in order to checkout/get or import a package. Once a package is checked out from SourceForge, mezzanine/CVS will remember where it came from and check it back into the same CVS repository. You should not set the CVSROOT environment variable as it makes it too easy to accidentally import code into the wrong CVS repository when working with multiple repositories.
Mezzanine needs to know to use the SourceForge CVS repository in order to checkout/get or import a package. Once a package is checked out from SourceForge, mezzanine/CVS will remember where it came from and check it back into the same CVS repository. You should not set the CVSROOT environment variable as it makes it too easy to accidentally import code into the wrong CVS repository when working with multiple repositories.
----
----
===Create your work area===
====Create your work area====
It is a good idea to perform all of your checkouts in a standard directory hierarchy. This makes it easier to move around between the packages. On a shared build server, it also makes it easier for people to recover your work if required (for example when you are on holidays). If you want to use filesharing to edit files from a networked PC, you might like to use <tt class="FILENAME">~/home/smeserver/</tt>. On a shared build server, you might even use something like <tt class="FILENAME">/builds/users/$LOGNAME/smeserver/</tt> so the files are not in your home directory and are accessible to all developers.
It is a good idea to perform all of your checkouts in a standard directory hierarchy. This makes it easier to move around between the packages. On a shared build server, it also makes it easier for people to recover your work if required (for example when you are on holidays). If you want to use filesharing to edit files from a networked PC, you might like to use <tt class="FILENAME">~/home/smeserver/</tt>. On a shared build server, you might even use something like <tt class="FILENAME">/builds/users/$LOGNAME/smeserver/</tt> so the files are not in your home directory and are accessible to all developers.
<div class="SECT2">
<div class="SECT2">
===Raise a Bugzilla entry===
====Raise a Bugzilla entry====
Before you make any changes to a package, you need to have a Bugzilla entry which specifies the problem and preferably proposes a fix. Raising the bug <span class="emphasis">''before''</span> you do the work allows others to comment on the proposed approach and can save significant time when you go to submit the changes. The change should also be approved by the Development Manager if it is meant for near-term release. You will need the Bugzilla bugid when you check in the changes.
Before you make any changes to a package, you need to have a Bugzilla entry which specifies the problem and preferably proposes a fix. Raising the bug <span class="emphasis">''before''</span> you do the work allows others to comment on the proposed approach and can save significant time when you go to submit the changes. The change should also be approved by the Development Manager if it is meant for near-term release. You will need the Bugzilla bugid when you check in the changes.
----
----
===Choose the package(s) to modify===
====Choose the package(s) to modify====
If you are modifying an existing file, the simplest way to determine the package is to install the relevant version and run '''rpm -qf''' on the file to be modified:
If you are modifying an existing file, the simplest way to determine the package is to install the relevant version and run '''rpm -qf''' on the file to be modified:
----
----
===mzgetsf_anon: SourceForge anonymous CVS checkout===
====mzgetsf_anon: SourceForge anonymous CVS checkout====
You can now retrieve one of the packages from SourceForge. In this case, we want to modify the <var class="LITERAL">smeserver-yum</var> package, so let's retrieve it from SourceForge:
You can now retrieve one of the packages from SourceForge. In this case, we want to modify the <var class="LITERAL">smeserver-yum</var> package, so let's retrieve it from SourceForge:
----
----
===Mezzanine package hierarchy===
====Mezzanine package hierarchy====
[gordonr@smebuild smeserver]$ cd smeserver-yum/
[gordonr@smebuild smeserver]$ cd smeserver-yum/
----
----
===mzclean: Clean out modified files===
====mzclean: Clean out modified files====
Before making changes to a package, you should ensure that you have a clean copy of the latest sources. Remember - other people may also be working on the package and making changes in SourceForge. You can perform a "merge" when you check in your changes, but it is easiest to start with an up-to-date copy. It is even possible that someone else has already fixed the bug you are working on!
Before making changes to a package, you should ensure that you have a clean copy of the latest sources. Remember - other people may also be working on the package and making changes in SourceForge. You can perform a "merge" when you check in your changes, but it is easiest to start with an up-to-date copy. It is even possible that someone else has already fixed the bug you are working on!
----
----
===mzprep: Build working tree===
====mzprep: Build working tree====
The '''mzprep''' command runs '''rpmbuild -bp''' on your SPEC file, sources and patches to generate a working tree. You can make changes in the working tree and use mezzanine to generate the patches between the previous version and your new files.
The '''mzprep''' command runs '''rpmbuild -bp''' on your SPEC file, sources and patches to generate a working tree. You can make changes in the working tree and use mezzanine to generate the patches between the previous version and your new files.
----
----
===SME Server package directory layout===
====SME Server package directory layout====
<div class="TABLE">
<div class="TABLE">
----
----
===The root directory hierarchy===
====The root directory hierarchy====
The <tt class="FILENAME">work/smeserver-yum-1.2.0/root/</tt> hierarchy contains the files which will be installed on the target machine.
The <tt class="FILENAME">work/smeserver-yum-1.2.0/root/</tt> hierarchy contains the files which will be installed on the target machine.
----
----
===Modifying a file===
====Modifying a file====
OK - now we can actually make a change. We want to modify the file which will be installed as <tt class="FILENAME">/etc/e-smith/events/actions/yum-import-keys</tt>, so the actual file we need to modify is: <tt class="FILENAME">work/smeserver-yum-1.2.0/root/etc/e-smith/events/actions/yum-import-keys</tt>.
OK - now we can actually make a change. We want to modify the file which will be installed as <tt class="FILENAME">/etc/e-smith/events/actions/yum-import-keys</tt>, so the actual file we need to modify is: <tt class="FILENAME">work/smeserver-yum-1.2.0/root/etc/e-smith/events/actions/yum-import-keys</tt>.
----
----
===mzpatch: Create a patch===
====mzpatch: Create a patch====
Mezzanine automates the creation of patches through the '''mzpatch''' command.
Mezzanine automates the creation of patches through the '''mzpatch''' command.
----
----
===Building a new package, with the patch===
====Building a new package, with the patch====
The next step is to change the package <tt class="FILENAME">SPEC</tt> file so that the patch is applied.
The next step is to change the package <tt class="FILENAME">SPEC</tt> file so that the patch is applied.
----
----
====Update the Release tag====
=====Update the Release tag=====
The <span class="emphasis">''first''</span> change you should make is to update the "Release" tag in the <tt class="FILENAME">SPEC</tt> file. You should do this by appending your initials and sequence number to the <var class="LITERAL">Release</var> number. In most SME Server <tt class="FILENAME">SPEC</tt> files, the <var class="LITERAL">Release</var> number is set via the <var class="LITERAL">release</var> macro, and so you should set it there.
The <span class="emphasis">''first''</span> change you should make is to update the "Release" tag in the <tt class="FILENAME">SPEC</tt> file. You should do this by appending your initials and sequence number to the <var class="LITERAL">Release</var> number. In most SME Server <tt class="FILENAME">SPEC</tt> files, the <var class="LITERAL">Release</var> number is set via the <var class="LITERAL">release</var> macro, and so you should set it there.
----
----
====Add a changelog entry====
=====Add a changelog entry=====
The SME Server project maintains history of packages changes in the <var class="LITERAL">%changelog</var> section of the <tt class="FILENAME">SPEC</tt> file. The changelog entry should be a simple description of the change of behaviour and must include a reference to an SME Server project Bugzilla entry (1174) and the new version number (1.2.0-05ff01):
The SME Server project maintains history of packages changes in the <var class="LITERAL">%changelog</var> section of the <tt class="FILENAME">SPEC</tt> file. The changelog entry should be a simple description of the change of behaviour and must include a reference to an SME Server project Bugzilla entry (1174) and the new version number (1.2.0-05ff01):
----
----
====Add a patch reference====
=====Add a patch reference=====
You now need to tell RPM to retrieve and apply the new patch. This needs to be done in two places, which is annoying, but allows for patches to be carried around, but not applied (e.g. because they are not quite finished). The first change is near the top of the file:
You now need to tell RPM to retrieve and apply the new patch. This needs to be done in two places, which is annoying, but allows for patches to be carried around, but not applied (e.g. because they are not quite finished). The first change is near the top of the file:
----
----
====mzbuild: Build a new package====
=====mzbuild: Build a new package=====
With all that done, you should be able to build a new package using '''mzbuild'''<nowiki>:</nowiki>
With all that done, you should be able to build a new package using '''mzbuild'''<nowiki>:</nowiki>
----
----
====Check the package====
=====Check the package=====
You should now perform some simple checks on the package before installing it for testing.
You should now perform some simple checks on the package before installing it for testing.
----
----
===Test your new package===
====Test your new package====
You should now upgrade your test system:
You should now upgrade your test system:
----
----
===Lather, rinse, repeat===
====Lather, rinse, repeat====
If you haven't fixed the bug, repeat the cycle: make changes, build a new patch, update the release number (e.g. to 05ff02, 05ff03, etc.), build a new package, test. Don't worry about using up release numbers.
If you haven't fixed the bug, repeat the cycle: make changes, build a new patch, update the release number (e.g. to 05ff02, 05ff03, etc.), build a new package, test. Don't worry about using up release numbers.
----
----
===Attach your patch(es) to the bug===
====Attach your patch(es) to the bug====
You should now attach your patch(es) and SPEC file changes to the appropriate Bugzilla entry. If the change is the simple application of a patch, you do not need to attach the whole SPEC file - just the changelog entry.
You should now attach your patch(es) and SPEC file changes to the appropriate Bugzilla entry. If the change is the simple application of a patch, you do not need to attach the whole SPEC file - just the changelog entry.
----
----
==SourceForge developer CVS access==
===SourceForge developer CVS access===
If you are going to work on many bugs, or wish to help with the many tasks involved in a release, you should create a SourceForge developer account.
If you are going to work on many bugs, or wish to help with the many tasks involved in a release, you should create a SourceForge developer account.
----
----
===Create a SourceForge account===
====Create a SourceForge account====
* Create a SourceForge user id
* Create a SourceForge user id
----
----
===mzgetsf: SourceForge developer CVS checkout===
====mzgetsf: SourceForge developer CVS checkout====
Once you have SourceForge CVS access, you can use '''mzgetsf''' (instead of '''mzgetsf_anon''') to retrieve the sources. Your copy will be writable and you will be able to put changes back to CVS. When you run '''mzpatch''' you should not see an error during the '''cvs add''' step.
Once you have SourceForge CVS access, you can use '''mzgetsf''' (instead of '''mzgetsf_anon''') to retrieve the sources. Your copy will be writable and you will be able to put changes back to CVS. When you run '''mzpatch''' you should not see an error during the '''cvs add''' step.
----
----
===mzput: Put the changes back to CVS===
====mzput: Put the changes back to CVS====
Instead of attaching the patch to the Bugzilla entry, you will be able to put it back to CVS. Mezzanine normally edits the <tt class="FILENAME">ChangeLog</tt>, but we don't need to do that as we keep the changes in the <var class="LITERAL">%changelog</var> section of the <tt class="FILENAME">SPEC</tt> file. The <var class="LITERAL">-m</var> option to '''mzput''' allows a simple comment to be appended, which is all that is required:
Instead of attaching the patch to the Bugzilla entry, you will be able to put it back to CVS. Mezzanine normally edits the <tt class="FILENAME">ChangeLog</tt>, but we don't need to do that as we keep the changes in the <var class="LITERAL">%changelog</var> section of the <tt class="FILENAME">SPEC</tt> file. The <var class="LITERAL">-m</var> option to '''mzput''' allows a simple comment to be appended, which is all that is required:
----
----
===Build the official package===
====Build the official package====
Official packages have unadorned release tags (e.g. smeserver-yum-1.2.0-05) and must be built on the official build servers. There are three steps involved - build the RPMs ('''mzbuild'''), sign the RPMs ('''rpm --addsign *.rpm''') and release the RPMs ('''release_rpms *.rpm''').
Official packages have unadorned release tags (e.g. smeserver-yum-1.2.0-05) and must be built on the official build servers. There are three steps involved - build the RPMs ('''mzbuild'''), sign the RPMs ('''rpm --addsign *.rpm''') and release the RPMs ('''release_rpms *.rpm''').
----
----
===mzimportsf: SourceForge package import===
====mzimportsf: SourceForge package import====
If a package has not already been checked into SourceForge CVS, you can use '''mzimportsf''' to import it. You should be careful to run this command from a directory which does not contain an imported package or mezzanine may import the package underneath the existing package.
If a package has not already been checked into SourceForge CVS, you can use '''mzimportsf''' to import it. You should be careful to run this command from a directory which does not contain an imported package or mezzanine may import the package underneath the existing package.
----
----
===mzmerge: Merge changed source RPM===
====mzmerge: Merge changed source RPM====
If a new source RPM has been built without corresponding changes in SourceForge CVS, you can use '''mzmerge''' to merge in the changes. This can also be used to merge in changes from a modified upstream package. Care should be exercised with this command, especially if you want to maintain previous patches.
If a new source RPM has been built without corresponding changes in SourceForge CVS, you can use '''mzmerge''' to merge in the changes. This can also be used to merge in changes from a modified upstream package. Care should be exercised with this command, especially if you want to maintain previous patches.
</div></div></div></div><div class="PART"><div class="TITLEPAGE">
</div></div></div></div>
</div></div>