Customizing Packages

This distribution uses the now common strategy of preserving the "pristine" sources and distributing them along with patches and the scripts necessary to automatically apply those patches during the build process.

This documentation is for developers who wish to modify the packages which come with Midori. We'll use a hypothetical software package called, "foo-6.18" for these examples.

For more detailed information, such as would be necessary to package new applications, refer to the file "midori/docs/mlz.txt" in the Midori tree.

Start from a working build.

Before setting off to customize packages, it's best to start from a working build. Create a ".precious" file in the cache/build directory of the package you want to change ("midori/cache/build/foo-6.18/" in our example) to protect your changes from being erased by the build scripts and experiment until you have your changes the way you want them.

Keeping a copy of what the directory originally contained (before customizing) would make it easy to "diff", of course.

Make a place for customized package sources.

After the first time Midori is installed and compiled, you will find a directory called "midori/cache/build/mlbuild-0.2/buildscripts/" (or perhaps a later version). "cd" to this directory and run the "setup" script, passing the full path of the directory where you will keep your customized package sources:


	cd  midori/cache/build/mlbuild-0.2/buildscripts/
	./setup  /usr/local/ml_custom

Important!: Be sure to edit the MIDORI variable in the new "Makefile.vars" file to point to the top of your Midori tree.

Unpack the package where you can modify it.

We'll begin with the package foo-6.18_ML2.4.mlz in our Midori "apps" directory, as it would be if we had been building Midori with this package included.

Go to your custom directory and from there untar the package you wish to customize:


	cd  /usr/local/ml_custom
	tar  -xzvf  /usr/local/midori/midori/apps/foo-6.18_ML2.4.mlz

Then add the package name and version to the "PACKAGES" variable in the main Makefile ("/usr/local/ml_custom/foo-6.18/Makefile" in our example) to read:


	PACKAGES=foo-6.18

This is where the changes which you decide to keep will be stored, under this custom directory.

Create the package-compatible patch.

Typically, packages invoke default procedures for unpacking the tar-ball and applying any patches. The default is to untar while in the "midori/cache/build/$PACKAGE" directory ("midori/cache/build/foo-6.18/" in this example). Patches are also run from that same current working directory by default. Read through the "build" script first to see if the package you want to modify is doing anything different. Look for functions named "ml_unpack" and "ml_patchit". If either is not present, its default will be used. If they do exist, look for the default function embedded in their code ("ml_unpack_default" and "ml_patchit_default"). As long as the default behavior is being used, you will be able to create a patch in the following way. Otherwise, things would be more complicated. "cd" to the package directory and untar the tar-ball. Then move it to a different name (possibly with a ".orig" extension). Then untar it again. Now, manually apply your patches or changes to the recently untar'd sources. From the package directory then, "diff" between the .orig sources and the ones you've modified to produce the patch:


	cd  /usr/local/ml_custom/foo-6.18
	tar  -xzvf  foo-6.18.tar.gz
	mv  -f  foo-6.18  foo-6.18.orig
	tar  -xzvf  foo-6.18.tar.gz

	(Here, apply your changes or patches.)

	cd  /usr/local/ml_custom/foo-6.18
	diff -urN  foo-6.18.orig  foo-6.18  >  my_change.patch

Be sure to name the file with the ".patch" ending. If it's very large and you want to save space, you can gzip it (leaving the name with a ".patch.gz" ending). Those names are automatically applied with "patch" by the default build function "ml_patchit_default".

One step more: In order for your patch file to be included in the package you must add it to the "SOURCE" list in the package's Makefile:

	SOURCE=CONFIG VERSION foo-6.18.tar.gz my_change.patch

After that, you can clean up by removing the directories which were untarred to make the patch ("foo-6.18.orig/" and "foo-6.18/"). Leaving them there won't hurt anything though. Since they're not listed in the SOURCE variable, they won't be included in the .mlz file.

Change the build script, if necessary.

If the package is not using the default functions for unpacking and patching the sources, then the build script may need changes for applying your patch.

Another reason for changing the build script would be if you wanted to make some sort of change dynamic, something which could only be determined at build-time (like a timestamp, for example).

Rebuild the package.

While in the top directory of your custom tree ("/usr/local/ml_custom"), do a "make". This should overwrite the corresponding .mlz file under the Midori "midori/apps/" directory with your modified one.

If you put a ".precious" file in the package directory in "midori/cache/build/", now is the time to remove it.

The next "make" done in the top of the Midori tree should then unpack your modified package into "midori/cache/build" and build it with your changes included.