Development Tools Overview (Monticello, SqueakSource, SqueakMap)
Last updated at 5:53 pm UTC on 17 January 2009
- Milan: Consider merging this work into Basic Squeak Development Tools
- (Milan Zimmermann's work in progress - not ready for use yet, but edit and improve freely!)
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/) :
- 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, see http://wiki.squeak.org/squeak/43#Running Monticello) and back end (Monticello Repository, see http://wiki.squeak.org/squeak/43#Opening a 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, only Monticello here, is described here.
- 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). The repository is web-broseable from http://map.squeak.org/packagesbyname.
- 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.
- 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.
- 4. SqueakMap Package Loader - see Using the SqueakMap Package Loader: Is a Morphic User Interface for Squeak Map which can load Packages (projects) from SqueakMap into your Squeak. Start it from Squeak World Menu->Open Menu->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). If you are a end-user who wishes to install a released Project into Squeak, you will use it. Compare list of projects in SqueakMap package Loader with it's web-based cousin, http://map.squeak.org/packagesbyname.
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|
|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), (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 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)"|
|ToDo How 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 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.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.
- 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).
This is a Version Browser of our eToysTests Project. Buttons on top do Action described below:
- 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.
Note that this maintains history even before we added this project on SqueakSource.
- 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
- 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).
- Open fresh 3.9
- Start Monticello Browser
- In Monticello Browser, Click +Repository
- On popup, type in something like:
- 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 - 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.