Last updated at 8:57 pm UTC on 23 September 2019
An easy one-time configuration to get Monticello history available for ones own private code in all images.
The primary goal of Personal SqueakSource was invisibility.
- 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 purposely 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.
Basically, it's code history that "just works" without having to change anything.
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.
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 virtual box.
Create a deployable ss.zip file
- Save a Squeak 5.2 image as 'ss.image', this is the name the scripts refer to.
- Install Personal SqueakSource from SqueakMap.
- From the Apps menu, click on 'RFB/VNC Server' and pin the submenu to the desktop, preferably near the top left of the screen. You will need this menu at various times.
- Set your password choices.
- Set an 'interactive password' if you already know what you want it to be in the deployed system
- Click on the 'allow empty passwords' if you do not yet know; this will let you connect via VNC later
- Set your 'connections' choices
- Unless you can guarantee local access with a display (not likely if you are setting up as a headless server ), click on the 'allow remote connections' option
- 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.gzNB: you can substitute other later releases but remember to use the appropriate filenames if you do... At some point we will revise the system to work with a final release VM
- If you wish personalise 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 web server 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 ss.zip file. In a Workspace run:
SSRepository deploy. "do it, ss.zip is created"It may take a while depending on your machine.
- Quit the ss.image
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:
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.
From the Linux command-line, run:
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" flavour 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.
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.
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.
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: