Squeak
  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 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/) :


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
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|
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:

        1. C belong to system category named "MorphicWrappers", OR
        2. C belong to system category name starting with "MorphicWrappers-".
        1. M belong to method category name "*morphicWrappers" OR
        2. M belong to method category name starting with "*morphicWrappers-".
        1. M belong to a class in the system category "MorphicWrappers", OR
        2. M belong to a class in system category with name starting with "MorphicWrappers-"
        3. 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.



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

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. SqueakMap http://map.squeak.org/


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.


- Test Project
- Save Squeak if you wish to keep the project


This completes the overview.