Hi,

I like David's proposal. It strikes a good balance between newbie friendly and detailed enough foundations (you don't learn Peano's Axioms before learning to count).

Cheers,

Offray

On 13/01/16 09:27, David Allouche wrote:
Hey,

Since I just recently figured that stuff out, my perspective might be useful.

I do not think it is a good idea to push external VCS too much at this point. They are important to collaboration, so they should be mentioned, but they add a lot of complexity.

Taking into account the feedback from Sven, and my own ideas, here's how I would write it. I hope this helps.

 1. The *virtual machine* (VM) provides the environment where the
    Pharo system lives. It is different for each operating system and
    hardware architecture, and runs as a machine language executable
    in the operating system. It implements the details of managing
    memory, executing Pharo byte-code, and communicating with the
    world outside of the Pharo system: files, other operating system
    process, and the network.
 2. The *image* is the state of all objects in a running Pharo system:
    classes, method as source and byte-code, windows, VM processes.
    All of those are objects. The virtual machine can load image
    files, and save running images back to disk.
 3. The *sources* file is a way to save space by putting the source
    code of classes outside of the image. Since an image contains
    byte-compiled methods, it can run without its associated sources
    files. This file only provides information that useful to the
    programmer. It is generated once per major release of Pharo, and
    is usually stored in the same directory as the image. Several
    images can use the same sources file.
 4. The *changes* file logs all source code changes since the
    generation of the sources file. It lets you examine and revert
    source code changes. It also serves as a journal so you can
    recover changes you made but did not save to the disk image, by
    mistake or because of a crash. An image does not need its changes
    file to run. Each change file belong to a single image.


NOTE: Some virtual machines run in web browsers, and are Javascript programs instead of machine language. They provide the same services as other virtual machines, they just treat Javascript as the machine language and the browser as the operating system.

The image, sources and changes files are portable across operating systems, and can be copied and run on any appropriate virtual machine. The format of the sources and changes file is defined by code stored in the image, not the VM.

A complete Pharo release contains the following files:

  * An executable virtual machine, named:
      o Pharo.exe for Windows;
      o pharo for Linux;
      o Pharo for OS X (inside a package named Pharo.app).
  * An image, named after the release: Pharo4.0.image
  * A sources file, named after the release: PharoV40.sources.
  * A nearly empty changes file, named after the image: Pharo4.0.changes


They are starting point for a live environment that you adapt to your needs. The .image file containes the byte-compiler of the language, the language parser, the IDE tools, many libraries and provide a virtual operating system that runs on top of a virtual machine.

As you work in Pharo, the .image and .changes files are modified, so you need to make sure that they are writable. The .image and .changes files are intimately linked and should always be kept together, with matching filenames. Never edit them directly with a text editor, as .images holds your live object runtime memory, which indexes into the .changes files for the source.

It is a good idea to keep a backup copy of the downloaded .image and .changes files so you can always start from a fresh image and reload your code. But to manage changes on larger projects you should also use a version control system that will provide more control to record and communicate your changes.

The four main component files above can be placed in the same directory, although it’s also possible to put the Virtual Machine and sources file in a separate directory where everyone has read-only access to them.

If more than one image file is present in the same directory pharo will prompt you to choose an image file you want to load.

Do whatever works best for your style of working and your operating system.

Reply via email to