Personal SqueakSource


	links to this page:

Last updated at 2:00 am UTC on 8 July 2022

Short Description

An easy one-time configuration to get Monticello history available for ones own private code in all images.

Requirements Solved

Personal SqueakSource provides a seamlessly integrated local SqueakSource repository for code in your local Monticello directory, allowing the IDE to provide additional features.

Two-click deploy. Step 1: #deploy. Step 2: copy to server, unzip, run.
Clean, rebuildable server image. No more custom images with workspaces, etc.
Zero code footprint. It works from the base trunk image with the base Monticello code.
Automatic server start and stop. Just boot your laptop, launch your image(s), and code history is just there and available.
Zero change to my workflow. I'm used to just saving code packages to my classic file directories. I don't want to have to remember to save them to some local HTTP repository. With Personal SqueakSource, you can save to either place, and it will be automatically replicated to the other. It's a dual-storage SSRepository.
Headless. I don't want to see the server window. Code history is just there, no need for user to be exposed to any aspect of the implementation. And yet, the production window can be seen and controlled through a VNC viewer.

Once set up, it's a reliable code history that "just works" without having to change anything.

Background

In 2003, a web-site for storing and sharing the code of Squeak projects was developed and deployed as http://www.squeaksource.com. Later, a separate instance of this same application (also known as "SqueakSource") was deployed as http://source.squeak.org, to manage the base image code itself.

This page describes a quick and easy way to set up a personal SqueakSource repository running on your laptop, which will enable the full Monticello history of one's own proprietary code to be made seamlessly available in all images.

System Requirements

Linux. The system generates the scripts needed for a Linux installation only. The automated server start/stop is achieved via the daemontools Linux utility. For other platforms, a similar utility such as a .bat file startup script, etc., could possibly be used, or a Linux virutal box.

Setup

Create a deployable ss.zip file

Save a Squeak 5.3 image as 'ss.image', this is the name the scripts refer to.
Install Personal SqueakSource from SqueakMap.
Save the image. This is the master image, it is saved and only ever launched in this idle state, no ports open and nothing running. The "run.st" script is invoked by the "run" linux script, which is invoked by the daemontools auto-run utility, to handle the server management.
Download https://github.com/OpenSmalltalk/opensmalltalk-vm/releases/download/201807260206/squeak.cog.spur_linux64x64_201807260206.tar.gz.
Move squeak.cog.spur_linux64x64_201807260206.tar.gz to a directory called 'vm' in the current directory. Then
```
    tar xf squeak.cog.spur_linux64x64_201807260206.tar.gz
```

NB: you can substitute other later releases but remember to use the appropriate filenames if you do...

If you wish personalize with your own logo, make sure a file named 'logo.jpg' is in the current directory. This file will be used as the logo at the top of your SqueakSource-based local website.
Make sure a file named webPort is in the current directory whose contents reflect the port you want the webserver to listen on. This can be created from the command-line via:
```
    echo 8080 > webPort
```
Make sure a file named rfbPort is in the current directory whose contents reflect the port you want the VNC to listen on. This is used to look at the running production image for diagnosing problems. This can be created from the command-line via:
```
    echo 5900 > rfbPort
```
Make sure SqueakV50.sources is in the current directory.
Make sure squeak.conf is in the current directory. It's contents should be:
```
*       hard    rtprio  2
*       soft    rtprio  2
```

Now generate the webserver.zip file:

       SSRepository deploy.  "do it, ss.zip is created"

Deploy and unzip ss.zip

Above, a file called ss.zip was created in the current directory. Move it to wherever you want to run the server, and unzip it:

  unzip ss.zip

Choose the name of your service

When the service is actually created below, it will be named according to the name of this directory ("ss"). If you wish to name it something other than "ss", now is the time. These instructions will continue to refer to it as "ss".

cd into ss. The setup scripts must be run from here.
The README file contains all of these instructions.

Run configsys

From the Linux command-line, run:

  ./configsys

It''s an idempotent script, running it more than once is the same as running it only once. It copies the Squeak HT VM configuration to /etc/..., enabling running of the improved "ht" flavor of Squeak VMs. It also installs daemontools (if not already installed) for the auto-start.
NOTE: After the first run of configsys, it is necessary to log out and back in.

Run exportscripts

The configsys script (followed by a reboot) allows the Squeak VM to actually work. Now we can run exportscripts, which instructs Squeak to generate the remaining scripts for this installation. The scripts will be generated to run a service as the currently logged-in user, at the current directory location, so if you wish for the server process to run as a different user, change to that user.

./exportscripts

Provide a /ss sub-directory

Now its time to soft-link your primary Monticello directory as ./ss. Yes, unless you renamed it, you will have an inner "ss" within your outer "ss" directory).

  ln -s /your/development/directory/mc ./ss

The directory structure of the inner ./ss is expected to have one folder per Project, with the mcz's in each folder. Each folder is represented as a SqueakSource Project (a.k.a., SSProject) within the in-image Monticello tool windows, as well as on the web interface hosted on localhost:[webPort].

Check for legacy 'data.obj' file

Unless a legacy data.obj file is present, one will be created with a Project for each subdirectory.

Create and start the service!

This last step will install the server as a daemon and keep it running even across reboots.

  ./configsvc

Troubleshooting

To verify the server is running, after a few seconds:

  sudo svstat /service/ss

It should say "up" for the several seconds (NOT 0 or 1 seconds) since running configsvc, above. Note the PID, run the svstat command again and verify its the same PID. If not, check files ./configsvc.out, ./ss.log, and ./log/main/current in that order, should provide enough clues to the cause.

You should also be able to point your browser to http://localhost:[webPort] and see the title screen.

About the Automatic Indexing

Personal SqueakSource performs its background "recovery" process on startup, which ensures any new files are in the Magma-based repository. Upon the first start, they're all new, so depending on how many .mcz files there are, full history will not be indexed until a few hours, but its a background process that won't interfere with development, and takes care of itself, so its okay to shutdown the computer even if its still running – it'll pick up where it left off next time.

Versions saved to the localhost:[webPort]/ProjectName will also be saved to your development directory (e.g.,ss), and be indexed immediately.

Making History available in images

The image-side tools pull the history from the first repository listed in that methods Monticello Package. So, to make the history available in images, the HTTP repository pointing to the http://localhost:8079/DirectoryName must be added to each MC Package.

The easiest way to accomplish this is to make your own subclass of Installer, add the 'package-definitions' method category and definitions like in Installer. That way, among other configuration conveniences, you can simply execute the following to add the correct locally running Personal-SS repository to all relevant packages:

  MyInstaller addLocalRepositories