User Tools

Site Tools


patching_system

The Package Manager

Etano has a complex module built to make upgrading and installing new mods/plugins very easy. The Package Manager module, which is part of the core script, can handle any modification in any file of the application, even if the file was slightly changed. Since Etano's code is not encrypted, you can make modifications to the files in your site to add new features on your own. But in case we release a patch, we didn't want to simply overwrite the file in case but we wanted to be able to implement our patch in the file modified by you, without loosing your changes. The Package Manager module should be able to handle this situation in most of the cases.

The Anatomy of a Modification Package

No matter if we release a patch to fix some bugs or new features or plugins/addons, the file you receive from us looks the same: it contains instructions for the Package Manager on what to do. We call this file a mod (short for modification) or a patch (patch mostly used when there are bug fixes). It is a zip file which contains a few other standard files.

The 2 standard files with instructions which are present in all packages are:

  • manifest.xml
  • install.mod

Apart from these you might also find:

  • .diff files
  • other .mod files
  • .php files
  • an ui/ folder
  • a files/ folder

manifest.xml

This file is the first file that the package manager reads when it starts installing the modification package. It contains general information about the package to be installed, its version, name, description and at least one install instruction. It looks similar to this:

<package id="module_code" name="a short name" version="1.12" type="0">
	<install>
		<requires id="core" version="2.2" change-version="2.3" />
		<requires id="other_module_code" version="1.03" />
		<text>1.11 to 1.12 patch</text>
		<modfile>install.mod</modfile>
	</install>
</package>

The first line in the example above says that the module "module_code" with the version 1.12 is to be installed. The "a short name" is the name displayed by the Package Manager when showing this mod. The code between <install> and </install> tags is an install instruction. There can be more than one install instructions in a manifest file. The lines that start with <requires inside the install instruction are specifying the dependencies of this mod. In the example, the mod will not be installed if your site doesn't already have the "core" module version 2.2 and "other_module_code" version 1.03 installed. The <text> tag contains the description of the package and <modfile> is the file with the actual install instructions. The file can have any name but we like to call it install.mod.

install.mod

This file is the file with all install instructions to be performed by the Package Manager to install the mod. Before running the instructions for real, the Package Manager first does a "dry run" (a test) with all instructions to make sure there's no error or conflict or any other problem. If even one instruction fails the test, then the whole installation is aborted. This is to make sure the mod won't overwrite some change you've made or break anything. In these situations you're shown an error with the file and maybe the line in the file where the error happened so you can investigate and take the required measures to fix the problem. The instructions the Package Manager knows about are:

  • <sql> - it runs an sql command (or file with more commands). This is for modifications in the database
  • <copy> - it copies files or folders from a place to another. Usually from the location where the package was unarchived to your site. We store all files to be copied in the files/ folder inside the modification package.
  • <delete> - deletes files or folders
  • <mkdir> - creates a folder
  • <extract> - unzips a zip file
  • <diff> - the location of the unified diff file which can do changes inside files, instead of simply overwriting them. This file format is explained separately below.
  • <php> - executes a php code.

.diff file format

The ability to work with unified diff files is the best feature of the Package Manager. What's important to know is that this is not just some obscure feature of the Etano framework but standard format that can be read by several tools, available on all platforms, not just Windows or Linux. With a small modification in the diff file you can even apply the changes in the file with a standard diff/patch tool. More on this below.

The format of the file is really simple. It goes like this:

for _this_ file, find the block of code that looks like _this_ and replace _this_ line and _that_ line with _this_ one and _that_ one.\\ 

This sequence can be repeated many times for other blocks of code and other files.

Index: includes/common.inc.php

This is the first instruction in a chunk. It tells that the code and instructions that follows are from file includes/common.inc.php (path relative to your site's base path). Since every site is installed in a different path, we couldn't use the full path of the file (e.g /home/user/public_html/includes/common.inc.php). So we put the relative path. If you want to use an external diffing/patching tool to apply this diff file to your site, you will have to add the base path to your site to all "Index:" instructions in the diff file. Also you need to remove the lines that start with +++ and — (see the code below) or add the base path to them too. That's the only modification needed.

===================================================================
--- includes/common.inc.php	(.../1.11)	(revision 660)
+++ includes/common.inc.php	(.../1.12)	(revision 660)

Lines like the ones above can be safely ignored.

@@ -63,6 +70,7 @@

This instruction tells that the code that follows can be found at line 63 in the original (unmodified) file and that there are 6 lines from the original code present. It also tells that the code after modifications will have 7 lines starting at line 70. The Package Manager doesn't rely on these line numbers for the simple fact that if you modified the code, the code that it is looking for might not start at that line. Instead it tries to find the actual location of the block of code.

All other lines in the diff file start with one special character and continue with lines of code from/for the actual files. There are 3 special characters used: - (minus sign) ⇒ it means that the line of code is to be deleted from the original file + (plus sign) ⇒ it means that the line of code is to be added in the original file " " (the space character) ⇒ the line is provided just for context - to help you identify where in the file is the code that has to be changed.

So a chunk like this:

Index: includes/common.inc.php
===================================================================
--- includes/common.inc.php	(.../1.11)	(revision 660)
+++ includes/common.inc.php	(.../1.12)	(revision 660)
@@ -63,6 +63,7 @@
 define('MODULE_FRAUD',2);
-define('MODULE_WIDGET',3);
 define('MODULE_SKIN',4);
+define('MODULE_3RD',5);
 
 // filter types
 define('FILTER_SENDER',1);

means that it has to delete the line with MODULE_WIDGET from between the lines with MODULE_FRAUD and MODULE_SKIN and to add the line with MODULE_3RD after the lines with MODULE_SKIN and before the " filter types" comment and the FILTER_SENDER line. You can read more stuff on the diff file format on the Wikipedia site. ==== Applying a .diff File With a Standard Patching Tool ==== As stated above, you need to add the full path to the files in the .diff file. If you don't know the full path just have a look at the includes/defines.inc.php file and copy the value for the _BASEPATH_ constant. But if you don't know how to find the full path where your site is installed maybe you shouldn't attempt to patch the site manually. Always backup all files before doing changes to your site. If your site is hosted on a linux server, it already has a patching tool installed (patch). You need to run this command from the command line: <code>patch -u file.diff</code> Obviously, you have to have access to the command line of your server. For Windows systems you could use the windows version of the same patch tool available here: http://gnuwin32.sourceforge.net/packages/diffutils.htm There may be other tools available. Winmerge is a great tool to see the differences between files and folders and may have patching capabilities too. ===== Installing a Modification Package ===== The easiest way to install a mod is to go to your admin panel - package manager - click on the button to check for new updates and click on the install link next to the mod you want. This will instruct your site to download the mod file from our server, copy it into its location and start the installation process. If you downloaded a mod package (zip file) instead of installing it directly you will have to copy it to your site into the tmp/packages/ folder and then go to your admin panel - package manager - you should see the mod in the list of mods available on your site and click install next to it. It is also recommended that you clean up the tmp/packages/ folder from time to time to prevent the slow down of the Package Manager. You can remove all files and folders from tmp/packages except .htaccess and index.html

patching_system.txt · Last modified: 2014/03/18 17:05 (external edit)