Hi guys. One month ago, I was running like crazy preparing my presentations for ESUG 2011. I had 3 talks and also the Fuel presentation in the awards. So…I was thinking about examples and demos to show with Fuel. I finally showed how to serialize a debugger and continue debugging it in another image, how to serialize a graph and store it in a Riak NOSQL database, how to use SandtoneDB with Fuel, etc. But I was not the only one running. Martin Dias, main author of Fuel, who was in the other part of the world, was also coding. He was trying to finish what I will show today: to be able to export and import packages using Fuel. Reality is different from movies. Hence, he could finally make it work, one day after the awards 😦
Since that day, we only focused in Fuel itself and we left the tool there. This week I went to work to Lille and Igor asked me to show him such tool. The tool at that moment was outdated (using an old version of Fuel) and quite buggy. Today, we have something better 🙂
UPDATE: As part of his excellent blog and screencasts, James Robertson has recorded a screencast where he follows the steps of this blog post. I recommend to take a look to it as well. Thanks a lot James!
What is the tool about?
As you may know, Fuel is a plain object graph serializer. No more than that. However, Fuel supports correct serialization of Class, Trait, MethodDictionary, CompiledMethod, BlockClosure, MethodContext, etc. Hence, creating a tool on top of that which allows one to export and import packages, is quite easy. In fact the tools is right now about 220 lines of code.
The tool is called Fuel Package Loader, but its name may change in the future. Basically what it does is to take a PackageInfo, extract the classes and extension methods, create a FLPackage instance and serialize that. During materialization (the import), we need to do extra tasks like registering classes in Smalltalk globals, in categories/organizations, notify about class creation, send class side #initialize, etc. In other words, this tool adds package semantics to a plain serialization.
Installing Fuel and Package Loader
As always, you have two options, pick up the latest bleeding edge build from our Jenkis job, or install with Metacello. For this post, use the Metacello way. The last stable version of Fuel is 1.6. But we needed to fix a couple of things on it in other to make FuelPackageLoader to work. However, Fuel right now is not “stable enough” to release 1.7 (we need to fix few things). Hence, I have created a temporal version 1.6.1 tagged as #development specially for this post. All this is because I want the post to be reproducible. So, pick up a Pharo 1.3 image (sorry, for older Pharo images we need to fix something very stupid but I don’t have time, but for 1.7 it will be fixed), and execute:
((Smalltalk at: #ConfigurationOfFuel) project version: '1.6.1') load: #('Core' 'PackageLoaderWithTests').
That will load Fuel, FuelPackageLoader and all their tests. Now, one of the best tests we can do for this project is to import and export Seaside web framework. Why? Because it is really big, it has a lot of packages, dependencies between them, a lot of important class side #initialize, etc. So…if we are able to import/export seaside, we should be able to import/export most of the existing projects.
Save this image as ‘Fuel.image’.
The first basic and naive idea we had when dealing with packages was to map one to one between Monticello packages and Fuel packages. Knowing which packages of Seaside are needed, in which other, and all the dependencies it has, is quite complicated. So…we can use Metacello for that. In the following example, we will install Seaside using Metacello and the regular packages of Monticello. But, we will at the same time, creat an associated Fuel package for each Monticello package. So, execute the following and wait between 10 and 30 minutes (if you are lazy, go directly to the import step where I provide the binaries):
((Smalltalk at: #ConfigurationOfSeaside30) project version: '3.0.6')
load: #('Core' 'Tests' 'Zinc-Seaside' )]
In this case, we have loaded the group ‘Core’ of Seaside, together with its tests and the Zinc seaside adaptor (just because I like it). Once that finishes, you can execute:
(ZnZincServerAdaptor port: 4242)
codec: GRPharoUtf8Codec new;
And now if you open the internet browser and go to http://localhost:4242/ you should see the nice Seaside welcome page.
Now, pay attention that a directory called ‘FuelMetacello’ was created in the same directory where the .image is. Inside that directory you can see all the generated fuel packages. Each of them are named with the pattern ‘prefix-packageName-fuel’. For example, ‘seaside-Scriptaculous-Core.fuel’, ‘seaside-Seaside-Flow.fuel’, etc. Those would be the equivalents to the Monticello .mcz and we will import them after.
Finally, save this image as ‘FuelSeasideExporter.image’
To import packages, all we need is to read the file and materialize them. But the problem is, in which order? mmmm Metacello used to know that, but not us. Well, this is why during export, we have also written a file that contains the script to import back. The file is called ‘prefix-load-script.txt’ (seaside-load-script.txt in this case) and it is also in the ‘FuelMetacello’ directory. If you open it, you can see its contents:
do: [ :packageFileName |
(FileDirectory default directoryNamed: 'FuelMetacello')
do: [ :aStream | FLPackageLoader new loadFrom: aStream binary ]]
displayingProgress: [ :packageFileName | 'Fuel importing ', packageFileName ]
So…. if you have followed the previous steps, then just open ‘Fuel.image’ (a new Pharo 1.3 image where Fuel is loaded but seaside is not), paste the previous code into a workspace and execute it. Of course that it depends on the machine, but here (Mac Book Pro i5), it only takes 10 seconds.
If you were a lazy gut who didn’t export the package, ok, here you have a zip of FuelMetacello. Just extract it and let the directory next to the .image.
It seems it was too fast to be working. So, if you don’t believe me, execute again the Zinc code to start a server (if you let the FuelSeasideExporter.image open, take another port) and then go to the browser. You should see, again the welcome page:
Ok, you still don’t believe it? Open the TestRunner, select all the seaside related tests and run it. They will be all green, or at least it should be exactly the same results as when running the tests from the FuelSeasideExporter image (where seaside was loaded with Metacello).
Why we put each package in a separate file? First because it was easier, and second because we wanted to be as much similar as possible with Monticello packages. In addition, this way, you can choose which packages to load. However, that doesn’t mean we are not able to serialize all packages in the same file, say seaside.fuel hahah. That’s possible, and it is easy since you can just download one file and you are done.
What the tool does and does not
As you may imagine the idea is that maybe in the future we can replace Monticello’ mcz with Fuel packages. Of course, we really far from there, but this was the first step. We tool right now:
- Sends class side #initialize to classes.
- Add classes to superclass instVar ‘subclasses’.
- Send notifications that a class was created
What it does not do so far (but we will try to do it in the future) is :
- Validations: we do not do validations at all. For example, we do not check whether a class we are materializing is already present in the image or if the global name was already taken. So we do not do class migration and things like that. In addition, we don’t validate class pools uniqueness and so on. So…right now the tool only works if you load in a clean image where you know there cannot be problems.
- Source code is not serialized. That means, when you import and browse the classes, you will see the decompiled source.
- .changes is not modified at all when loading a package.
- Traits are partially supported and not really tested (soon will be fixed).
This tool is similar to VisualWorks Parcels, but there is a big difference. Parcels was designed with the idea in mind of managing code. Hence, it is a little bit “coupled” with that. It is difficult to use Parcels as a plain serializer. Fuel is a general-purpose serializer and coupled with nothing. It is an infrastructure where we can then build tools on top of that. FuelPackageLoader is just an example of that. In 220 lines of code we where able to have something more or less working for importing and exporting packages. We can export seaside (96 packages!!!) in 12 seconds and import them in 10. Ok, we still need to add a lot of missing features that will probably have overhead. But so far, the results are promising.
Do not use this tool for production. It is just an experiment and it is really really in development. Just try it for fun. If you want to help us, try importing/exporting your own packages instead of seaside and let us know if you have problems!
Finally, a big clap clap to Martin who has been working a lot in Fuel and the package loader.