links to this page:    
View this PageEdit this PageUploads to this PageHistory of this PageTop of the SwikiRecent ChangesSearch the SwikiHelp Guide
Development Tools Overview (Monticello, SqueakSource, SqueakMap)
Last updated at 5:53 pm UTC on 17 January 2009


Developement Tools Overview (Monticello, SqueakSource, SqueakMap).


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, SqueakSource, SqueakMap - what are they for?

They are tools to manage your Squeak code, and it's packaging and releases. Four 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/) :

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

TermDescriptionSample ToolCorresponding Squeak Tool

Source Code Control (Development Process)Managing source code that is part of one or more projects. May include managing versions, history, releases, etc.CVS client (user interface), server (manager) and repository (backend store)Monticello Browser (user interface),
Monticello Repository: 
(manager and backend store)
Package (Development Process)A unit of code (multiple classes) that are managed as one "unit" in for development or release. Monticello using the word "Package" for source code control is perhaps confusing, as "Package" often defines collection of installable binary that provides certain functionality (Linux RPM package). But anyway, the term "Package" or "Monticello Package" will be used to describe a unit of managed code..rpm file, .deb file .mcz file

Version Management (Development Process) Ability to mark certain state of code as a "version"CVS tag (e.g. 2.0.17)Monticello Version, for example, MorphicWrappers-mz.2017

Package Repository (Distribution Process)Place which holds packaged software, available for users to be installed on their system.In Linux, http or ftp repository of .RPM, .DEB packages. For example, SuSE Linux repository of KDE core packages is on http://download.opensuse.org/repositories/KDE:/KDE4:/STABLE:/Desktop/openSUSE_11.1/. Repository can be accessed by web browser, but to install packages on user's system a Package Installer such as Yast or Yum is typically used. SqueakMap - all packages repository is located on http://map.squeak.org/packagesbyname. As in the Linux equivalent, SquekMap Repository can be accessed by web browser, but to install packages on user's system a Package Installer such as SqueakMap Package Loader is typically used.

== continue cleanup here vvvv ===

Package InstallerAllows 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)"

ToDo How to explain difference between Monticello Repository and Monticello Repository on SqueakSource? Source Code RepositoryPlace which holds source code, shareable by developersCVS RepositoryTODO Monticello Repository (Backend)
Monticello Browser (Client, this is what developer uses)

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 and methods that you want to manage as a Package.

1.2 If you have larger amount of code that you want to manage as Monticello Package, see Sidenote: Creating Monticello Package from Existing Code

1.4 ====== TODO ====== 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.

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. SqueakSource - http://www.squeaksource.com

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).

  1. To create a new Project on SqueakSource, let's go to http://www.squeaksource.com
    1. Create a new login account if not a user already.
    2. Process to Register a new Project:
      1. Once logged in to SqueakMap, on the left, click on "Register Project", Uploaded Image: mc-squeaksource-register-project.png as in the screenshot.
      2. 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.
      3. 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. Uploaded Image: mc-squeaksource-project-created.png Below, when adding Monticello code Package to the Project we created, we will be pasting the Registration string into Monticello Browser.
  2. Having created a new SqueakSource project, this step will create a Monticello Repository on SqueakSource for our project.
    1. 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.
    2. 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.
    3. In the Monticello Browser, let's click on +Repository. This will open dialog similar to the one below, select "http": Uploaded Image: mc-add-SqueakSource-as-repository.png 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.
    4. Next dialog specifies the HTTP allocated for our project on SqueakSource that you created above. Uploaded Image: mc-specify-SqueakSourceaddress.png Here is where we can simply paste the Registration item, and add your password and click "Accept".
    5. 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 Uploaded Image: mc-squeaksource-etoys-repository-created.png
    6. In the above dialog, fill in your comment, and click "Accept". All we have done so far corresponds to "CVS Import".
    7. After "Accept" in the above step, A Version Browser will come up. Uploaded Image: mc-add-etoys-version-browser.png
This is a Version Browser of our eToysTests Project. Buttons on top do Action described below:
      1. Browse what is in the Repository on SqueakSource - see Uploaded Image: mc-add-etoys-repository-browse-snapshot.png
      2. 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.
      1. Changes Shows any changes in your image compared to the version in SqueakSource repository. Because we just created the repository, there are no changes. Uploaded Image: mc-add-etoys-repository-changes.png
      2. Load will load the version from Repository into our image.
      3. 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?
      4. Adopt Adopt the SqueakSource version as ancestor of your working copy. QUESTION what does this mean?
      5. Copy Copy this version to another repository. Uploaded Image: mc-add-etoys-repository-copy.png
      6. Diff Create an equivalent version based on an earlier release. TQUESTION what does this do? Uploaded Image: mc-add-etoys-repository-diff.png

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).

- Open fresh 3.9
- Start Monticello Browser
- In Monticello Browser, Click +Repository
- On popup, type in something like:
	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. SqueakMap http://map.squeak.org/

3.1 SqueakMap for Project Owners/Developers: How to publish a released project on Squeak Map:

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.

This completes the overview.