Development Tools Overview (Monticello, SqueakSource, SqueakMap)
Last updated at 4:22 am UTC on 26 February 2007
Milan: Consider merging this work into Basic Squeak Development Tools
Developement Tools Overview (Monticello, SqueakSource, SqueakMap).
(Milan Zimmermann's work in progress - not ready for use yet, but edit and improve freely!)
This is an overview/tutorial, based on my limited use of Monticello, SqueakMap and SqueakSource, describing what they are for, and how to use them to manage Source Code and Release Projects.
The Goal of this Overview: To help myself not to forget, over a long periods between using Squeak, how to do "Source Code Control", "Team Developement", "Release Management", and "Creating an Installer" in Squeak. Hopefully other new Squeak developers will find some value in this.
Monticello, SqueakMap and SqueakSource - what are they for?
They are tools to manage your Squeak code, and it's packaging and releases. The 3 bullets below are a brief description of those tools, in the order a developer should encounter these tools. (Also see the table below in "Project Terms and Comparison of Tools" , and http://www.squeak.org/Features/Development/) :
- 1. Monticello - http://www.wiresong.ca/Monticello/: Is a Source Code Control tool and also a Source Packaging tool. It has a front end (Monticello Browser) and back end (Monticello Repository). The Repository can be a "directory", a "http" site, "ftp" site, or directly the SqueakMap. Source code control and packaging in Squeak can be performed using other formats, such as SAR and Changesets, but we will only be describing Monticello here, as it is the best tool (partly subjective of course).
- Project Management using Monticello:
- Single developer project would typically be managed as a "directory type Monticello Repository" stored on his/her local system.
- Multi-developer projects would typically be managed in a "http type Monticello Repository", with it's http address, pointing to, for example, SqueakSource (see below).
- How does developer create a Monticello Repository?
- For "directory type Monticello Repository", developer uses the Monticello Browser to both create the repository, put source in it, and manage the code changes.
- For "http or ftp type Monticello Repository", Repository must be started on a ftp or http server. However, an existing public repository exists - SqueakSource, see item below, also 2.1. In a typical situation, developer does not create a http repository, he would simply use SqueakSource as "existing Monticello repository".
- 2. SqueakSource - http://www.squeaksource.com: Is a Repository for Packages under development.
- If you want to use it to as your Monticello projects Repository, you need to create a SqueakSource login on http://www.squeaksource.com.
- What is the relationship between Monticello and SqueakSource? SqueakSource can be used as Monticello Repository of "type http", so in a way, SqueakSource is a public "database" of Monticello Repositories. For projects developed by multiple developers, using SqueakSource instead of local directories is a good idea. If you jump to Step 1.4 below, and create a "http type" repository, (instead of a "directory type" used in Step 1.4), and point http to SqueakSource, you would have created your repository on SqueakSource.
- 3. SqueakMap - http://map.squeak.org/: Is a central Repository of Released Projects, along with standardized information about the Projects (alpha, beta, author, about, etc).
- What is the difference between SqueakMap and SqueakSource? SqueakMap holds an equivalent of "Released Projects", while SqueakSource is a repository for "Projects in Development". Apart from that, all the ideas, and mechanics of creating projects on SqueakMap and SqueakSource are very similar.
- If you are a developer who has a project that you want to release for others to use, you need to create a SqueakMap login on http://map.squeak.org/, and register your project.
- If you are a end-user who wishes to install a released Project, SqueakMap has a Morphic client named SqueakMap Package Loader, which you can start from Squeak World Menu->Open Menu->SqueakMap Package Loader. SqueakMap Package Loader allows to find and install (load) released Squeak software into your image, so it is like Add/Remove Programs on Windows, or Yast, Yum or Apt-get in various flavours of Linux, but without the benefit of resolving Package dependencies (so far).
- Projects on SqueakMap:
- May be uploaded to SqueakMap OR
- Linked from other repositories, such as SqueakSource.
- SqueakMap also has info about Squeak developers and other items of interest.
- Note that, even though SqueakMap uses the term "Package", I am using the word "Project" as a synonym for "installable unit" from SqueakMap, because in general, when user click on an item in SqueakMap Package Loader, one or more Packages may be installed into your Squeak. See Step 3.1 on how one SqueakMap item can install multiple Monticello Packages.
Project Terms and Comparison of Tools
Let us take a few terms, and compare them with more traditional environments, where source code control is "file based". Also see http://www.squeak.org/Features/Development/ and http://wiki.squeak.org/squeak/4
TODO: fix this, this is incorrect vvv
Term | Description | Sample Tool | Corresponding Squeak Tool |
TODO |Source Code control|Managing source code that is part of one or more projects. Likely includes managing versions, history, releases, etc.|CVS server and repository/CVS client|TODO Monticello Repository (Backend) / Monticello Browser (Client, this is what you will see and work with as developer)|
TODO |Package|A unit of code (several classes, methods) that are managed as one "unit" in the release system. I believe Monticello using the word "Package" for source code control is somewhat unfortunate, as "Package" is typically used either as source structure tool (Java package keyword), or in the release stage (Linux RPM package). But anyway, we will use the term "Package" or "Monticello Package" to describe a unit of managed code.|.rpm file, .deb file |.mcz file|
TODO |Project|One or more Packages that need to be installed together for them to function.|CVS project|One or more Monticello Packages exported to SqueakSource|
- "Project needs to have a more unique name." Projects in squeak are associated with the .pr squeaklets that appear when you save project to disk or load project from disk. wiz
- (So maybe Package Project???)
OK |Team Developement|Ability for multiple developers to work on the same project, edit same pieces of code, and resolve conflicts if more then one developer edits the same piece of code (typically line(s) it traditional file-based systems).|CVS server and repository|Monticello Repository, which can be stored in a directory or on SqueakSource|
OK |Version Management| Ability to mark certain state of code as a "version" (e.g. 2.0.1)|CVS tag|Monticello Version|
Error: this should not happenError: this should not happenTODOError: this should not happenError: this should not happenHow to explain difference between Monticello Repository and Monticello Repository on SqueakSource? |Source Code Repository|Place which holds source code, shareable by developers|CVS Repository|TODO Monticello Repository (Backend) / Monticello Browser (Client, this is what you will see and work with as developer)|
OK |Package Repository|Place which holds packaged software, ready to be installed. |In Linux, http or ftp repository or .RPM, .DEB packages|SqueakMap|
OK |Package Installer|Allows to install packaged software from Package Repository (see above). |Yast, Yum, Apt-get (installs into linux, resolves dependencies)|SqueakMap Package Loader (installs into your image, NOT the OS). Note that in Squeak's SqueakMap Package Loader, resolving dependencies is weak (almost nonexistent, ususally defined as instructions "install A,B,C before D)"|
Steps to use Monticello, SqueakMap and SqueakSource to Manage a Project.
This tutorial will describe steps that I had to do when I wanted to manage a project (MorphicWrappers) using Monticello, the "new" squeak Source Code Control tool, and store and maintain the code as a project on SqueakSource and SqueakMap. The code existed before I started using it, but always managed using the "old" Changesets (also did not load in new versions of Squeak, but that is not relevant for this tutorial).
1. Monticello - http://www.wiresong.ca/Monticello/. Manage your source code. Even for a small personal package or project.
Steps in this Section 1 describe how to use Monticello as a "Source Code Control" system in Squeak. Monticello is an equivalent of CVS in file-based systems. It makes sense to manage all projects, including small personal projects using Monticello. Monticello is much simpler than Changesets, but may have disadvantages for projects with overwrites, see ChangeSorter vs. ChangeSet vs. Monticello (but then again, we should NOT use overwrites).
1.1 Create some Squeak classes or take existing Classes and methods that you want to manage as a Package.
If you did not write any code for your Package yet, and want to first create the "code repository" in Monticello, and then start writing code, skip to Step 1.4, which will create an (empty) Monticello Repository for your Package, but read Steps 1.2 and 1.3.
1.2 Ensure your classes and methods will be recognized as your "Monticello Package". This tutorial will use MorphicWrappers as an example name for the Monticello Package. In your Package, just substitute MorphicWrappers for any name you choose.
Monticello uses naming conventions to define classes and functions to be members of a particular project. So any class and method that you want to be part of your package, must adhere to such naming conventions, listed below. The naming conventions below are re-worded from the original http://www.wiresong.ca/Monticello/UserManual/PackageInfo/:
A Monticello Package named "MorphicWrappers" contains Classes and Methods based on the following Rules:
- CLASS RULE 1, BASED ON system-CATEGORY NAME: Monticello project contains
- C belong to system category named "MorphicWrappers", OR
- C belong to system category name starting with "MorphicWrappers-".
- METHOD RULE 1, BASED ON METHOD-CATEGORY NAME and METHOD-NAME): Monticello project contains
- all method definition M where
- M belong to method category name "*morphicWrappers" OR
- M belong to method category name starting with "*morphicWrappers-".
- METHOD RULE 2, BASED ON system-CATEGORY NAME: Monticello project contains
- M belong to a class in the system category "MorphicWrappers", OR
- M belong to a class in system category with name starting with "MorphicWrappers-"
- MINUS methods which method category starts with "*" (then the method must belong to other module).
TODO: WHY is RULE 1 only talking about classes? Does it mean that if a class belongs to a Package according to Rule 1, that says absolutely nothing about where do the class' methods belong? Also, why does Rule 2 say method definition" while Rule 3 says "method"?
1.3 Collect all classes and methods which will be part of our "Monticello MorphicWrappers Package" into one Changeset, named MorphicWrappersChangeset.
Describing Changesets is beyond this tutorial, and requires some knowledge of Changesets. However, most users of this tutorial, should either start which creating a Monticello package first and start on Step 4, or start writing code which will by default end up in one Changeset, and no awarness of Changetsets is necessary. TODO-milan: Check what happens if code is in multiple changesets. It may not matter at all, and Monticello will do the right thing without user knowledge of Changesets.
1.4 Convert the MorphicWrappersChangeset into "Monticello MorphicWrappers Package" named MorphicWrappers. This step will also create the Monticello Repository that stores code for the package.
First, a short introduction of this step. This step will create what is called the "Monticello Repository". Monticello repository is a storage of the code. It can be stored as "Directory", "HTTP", "FTP", "Squeakmap Release" and others. We will have an option to select one of them a bit later, but as a general comment, each of these "storage typess" is capable of storing and managing our package. Each package will have an extension ".mcz", so in our case, we will have MorphicWrappers.mcz. While creating a Squeakmap release here would be a shortcut, we will go slowly in this tutorial, and first create a "directory" type repository on your local machine. This repository can be used later on to create the "final", or "releasable" version on SqueakSource and from there, SqueakMap.
- Red-click (Left-click) on the Squeak desktop (world), a menu appears, click "Open"
- In the "Open" menu, click on "Monticello Browser". The "Monticello Browser" window appears. On the left, you should see line with your changeset name, MorphicWrappersChangeset. Click on this line.
- In the Monticello Browser, click on the "+Package". This will create, in the left pane, a line named "MorphicWrappers()". Essentially, this has created, but not saved yet, our new package (unless it exists).
- On prompt, name the package MorphicWrappers
- Click on "+Repository", select the RepositoryType "directory", which will popup a File Manager.
- In the File manager, middle click (blue-click) and "add directory" MCZ-REPOSITORY. Still in File manager, highlight the new MCZ-REPOSITORY directory in the right pane (./MCZ-REPOSITORY/MorphicWrappers.mz.1.mcz). Click OK. This will close the File manager.
- We are back in Monticello Browser:
- Make sure the ./MCZ-REPOSITORY/MorphicWrappers.mz.1.mcz is still highlighted on the right.
- Make sure *MorphicWrappers is still highlighted on the left.
- Click "Save". On prompt, type in description of the new Package, for example "Our Morphic Package"
- The "Save" will create the repository for our package, which is simply a file named ./MCZ-REPOSITORY/MorphicWrappers.mz.1.mcz, and collect into it, as described in Step 2:
- All classess in System Category which name starts with "MorphicWrappers-"
- All methods which Method Category name starts with "*morphicWrappers-"
- All methods by iterating all classes that belong to System Category which name starts with "MorphicWrappers-" EXCEPT methods which names start with "*"
- A "Version Browser" will also be open on top of Monticello browser. "Version Browser" has buttons to browse, load, reject, and merge changes manually if user wishes to do it, but mostly, only the browse button will be used.
- If you need to add any other package, start on top of this buletted list, but your Package name will be different.
- Next time you make a change in code of any class or method that belongs to your Package, you simply:
- Open the Monticello Browser
- Highlight the MorphicWrappers line on the left (Package name)
- Click Save, which will create a new version MorphicWrappers.mz.2.mcz (note the "2") of your package.
- Monticello automatically manages differences and changes.
1.5 Notes on Monticello:
Question I collected on the list: I can't just click on Merge - it is greyed out. Do I need to "Keep" each of
the highlighted conflicts in order to proceed with the Merge?
Answer: Ah, yes. If you have selectors displayed in bold, it means you have conflicting changes and need to decide whether to "keep" the incoming change or to "reject" the incoming change (and I hate these terms, and hopefully I got them right this time). You can only proceed with the merge once you've decided how to deal with the conflicts. Notice that often the "rest local" or "rest remote" buttons are what you really want. The first one (rest local) means "I want my local changes to prevail" whereas the latter says "I want what's current in the repository".
2.1 SqueakSource for Package Authors: How to put a Monticello Package on SqueakSource.
This section describes how to create and maintain a Project on SqueakSource as a Monticello Package. (Note that a Project on SqueakSource can be maintained in other formats, as a changeset, .sar etc, but we are only interested in Monticello).
- To create a new Project on SqueakSource, let's go to http://www.squeaksource.com
- Create a new login account if not a user already.
- Process to Register a new Project:
- Once logged in to SqueakMap, on the left, click on "Register Project",
as in the screenshot.
- A new page will show, where we fill in the project name (no spaces), description eToys and Morphic Tests in our case, creator, administrator etc. Here we can specify other developers' access to the project. Then we click "Save" on the bottom of the page.
- The above step created a new Project on SqueakSource with properties similar to those in the screenshot below. The interesting part is Registration, which is instructions that allows to publish our Monticello Package on SqueakSource.
Below, when adding Monticello code Package to the Project we created, we will be pasting the Registration string into Monticello Browser.
- Having created a new SqueakSource project, this step will create a Monticello Repository on SqueakSource for our project.
- Open the Squeak image with the latest version of project (eToysTests in our example) we want to publish. In World, let's red-click "Open"==>Monticello Browser.
- On the left, we click on our Package once (another click will deselect). Remember that Package corresponds to a Class Category, and must be selected, before we create a Repository for it.
- In the Monticello Browser, let's click on +Repository. This will open dialog similar to the one below, select "http":
By the way, the if you want to create a "local repository" on your system, as opposed a repository on SqueakMap, select "directory" - that is the only difference!. Your source code control would then be on your local system directory.
- Next dialog specifies the HTTP allocated for our project on SqueakSource that you created above.
Here is where we can simply paste the Registration item, and add your password and click "Accept".
- The above step so far created an empty repository for our project. We now have to "Save" our project into the repository. In Monticello Browser, make sure eToysTests-Kernel.... is selected on the left, and http://squeksource.com/eToysTests is selected on the right! Then click "Save". See
- In the above dialog, fill in your comment, and click "Accept". All we have done so far corresponds to "CVS Import".
- After "Accept" in the above step, A Version Browser will come up.
This is a Version Browser of our eToysTests Project. Buttons on top do Action described below:
- Browse what is in the Repository on SqueakSource - see
- History Shows full "Save History" of your project. Basically, for every Commit/Save we see one item. History is as if every CVS commit put a tag on your project. +mc-add-etoys-repository-history.png
Note that this maintains history even before we added this project on SqueakSource.
- Changes Shows any changes in your image compared to the version in SqueakSource repository. Because we just created the repository, there are no changes.
- Load will load the version from Repository into our image.
- Merge Would merge the version from repository into image. This is applicable AFTER we would have made changes into our image that affect the project, and in the meantime, the repository on SqueakSource would be updated (new version would be created). This is like "CVS Update". TODO- what happens if there are conflicts?
- Adopt Adopt the SqueakSource version as ancestor of your working copy. QUESTION what does this mean?
- Copy Copy this version to another repository.
- Diff Create an equivalent version based on an earlier release. TQUESTION what does this do?
2.2 SqueakSource for Package Developers: How to Install and existing Project into your Squeak Version from SqueakSource:
This step would be used by any Developer that participates in the project development. A general Project User would install the project once it is published on SqueakMap (NOT SqueakSource).
TODO:
- Open fresh 3.9
- Start Monticello Browser
- In Monticello Browser, Click +Repository
- On popup, type in something like:
=============
MCHttpRepository
location: 'http://www.squeaksource.com/MathMorphsRevival'
user: 'mz'
password: 'HIDDEN'
=============
- Accept
- The repository should be added to the menu on the right and highlighted
- Blue-click on the highlighted repository, select "open repository"
- this will open a new window on the Repository
- In the Repository window, click on "MorphicWrappers.mz.1.mcz", then click "Load" button
- In the Repository window, click on "Functions.mz.2.mcz", then click "Load" button
- These 2 steps load the code into your image
- Examples of Function Plots can be run as described at the bottom of "Overview" in step 1
- You both should have access to modify these MCZ
3.1 SqueakMap for Project Owners/Developers: How to publish a released project on Squeak Map:
todo
TODO - Script which installs MorphicWrappersRevival - todo project on SqueakMap - see SqueakMap-install-MathMorphsRevival.st
3.2 SqueakMap for Project Users: How to install Project from SqueakMap into your Squeak.
For the end-user who wishes to install a released Project, for example, MathMorphsRevival, SqueakMap has a Morphic client named SqueakMap Package Loader, that you can start from the World Menu->Open Menu->SqueakMap Package Loader. This tool will connect to SqueakMap with all the released projects, and allow you to select a version suitable for your system, and install it in your Squeak image.
- Start Squeak
- If the project is not installed yet, it will show on the left as 'MathMorphsRevival()'. Click World Menu->Open Menu->SqueakMap Package Loader.
- You may get question: "selected release is not published yet, install anyway"?, answer "yes". Project should install.
- You will know the project is installed, when it shows on the left with version number, for example, 'MathMorphsRevival(0.1.1)'.
- Test Project
- Save Squeak if you wish to keep the project
This completes the overview.