Repository: pharo-open-documentation/pharo-wiki
Branch: master
Commit: 45f56f06b43e
Files: 58
Total size: 358.7 KB

Directory structure:
gitextract_8rwhc7yu/

├── .github/
│   └── workflows/
│       └── continuous.yml
├── .gitignore
├── CONTRIBUTION.md
├── ExternalProjects/
│   ├── DataStructures/
│   │   └── DataFrame.md
│   └── Export/
│       ├── Arff.md
│       ├── CSV.md
│       ├── ESCP.md
│       ├── HTML.md
│       ├── JSON.md
│       └── XML.md
├── ExternalResources/
│   └── Community.md
├── General/
│   ├── Baselines.md
│   ├── CJKCharacter.md
│   ├── CJKInputMethod.md
│   ├── CodingConventions.md
│   ├── CoolSnippets.md
│   ├── DeployYourPharoApplication.md
│   ├── Exceptions.md
│   ├── ExportFormats.md
│   ├── Extensions.md
│   ├── Files.md
│   ├── GithubActions.md
│   ├── Glossary.md
│   ├── HowToRunPharoFromCommandLine.md
│   ├── IcebergOnWindows.md
│   ├── ImageFileFormat.md
│   ├── Inspector.md
│   ├── InterestingsToKnowForBeginners.md
│   ├── Layout.md
│   ├── MenuBar.md
│   ├── MustKnowForBeginners.md
│   ├── Playground.md
│   ├── Pragmas.md
│   ├── Profiling.md
│   ├── ProgressBar.md
│   ├── Refactorings.md
│   ├── SessionsManagement.md
│   ├── SettingUpANewProject.md
│   ├── Settings.md
│   ├── SortingCollections.md
│   ├── Traits.md
│   ├── Travis.md
│   ├── TweakingBigImages.md
│   └── Windows10SubsystemForLinux.md
├── LICENSE
├── MANIFEST.md
├── Migration/
│   └── MigrationToPharo7.md
├── PharoProjects/
│   ├── Announcer.md
│   ├── Cursor.md
│   ├── DynamicVariables.md
│   ├── Metalinks.md
│   ├── Numbers.md
│   ├── OS.md
│   ├── ObjectsSerialization.md
│   ├── RichText.md
│   └── WebBrowser.md
├── PharoVirtualMachine/
│   └── pharo-vm-map.md
└── README.md

================================================
FILE CONTENTS
================================================

================================================
FILE: .github/workflows/continuous.yml
================================================
name: Broken links

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the development branch
on:
  push:
    branches:
      - 'master'
  pull_request:
    types: [assigned, opened, synchronize, reopened]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Defining a new Environment Variable
      run: |                          
        TEMPFILES=$(ls **/*.md)    
        echo "FILES<<EOF" >> $GITHUB_ENV
        echo $TEMPFILES >> $GITHUB_ENV
        echo "EOF" >> $GITHUB_ENV
    - uses: docker://dkhamsing/awesome_bot:latest
      with:
        args: --white-list travis-ci,127.0.0.1,smalltalkhub.com/mc,github.com/MY_USERNAME/MY_PROJET_NAME --allow 403 --allow-dupe --allow-redirect --skip-save-results ${{ env.FILES }}


================================================
FILE: .gitignore
================================================
**/.DS_STORE


================================================
FILE: CONTRIBUTION.md
================================================
# Contribution guidlines

  * [Suggest new pages](#suggest-new-pages)
  * [Entries structure](#entries-structure)
  * [Edit a page](#edit-a-page)
  * [Add a new page](#add-a-new-page)
  * [Deleting, Moving or Renaming a page](#deleting-moving-or-renaming-a-page)
    + [If the content is obsolete](#if-the-content-is-obsolete)
    + [If we want to move a page](#if-we-want-to-move-a-page)
    + [If we want to split a page](#if-we-want-to-split-a-page)
    + [If we want to rename a page](#if-we-want-to-rename-a-page)
  * [Review content](#review-content)

## Suggest new pages

To suggest pages that could fit the wiki, the recommended way is to open an issue containing a summary of the page, the section in which it should be (General, Internal projects of Pharo or External projects of Pharo) and optionaly links to already existing documentation on the projects.

On the language and environment part of the wiki we accept to document a part of the system that is already documented outside the wiki at the condition that we reference in a *See also* section those documentation. The goal is to have a centralized information and to provide alternative ways of explaining.

If you wish to add the new entry yourself, see section [Add a new page](#add-a-new-page).

## Entries structure

The entries structure is free but we still have some conventions. 

* Documentation on external projects should mostly contains small example, comparaisons between multiple projects, links to official documentations and repositories. We can accept documentation on the external projects in case there is none by the official maintainer.
* Long entries should begin with a table of content. We recommand [https://ecotrust-canada.github.io/markdown-toc/](https://ecotrust-canada.github.io/markdown-toc/).
* References to external/decentralized documentation should be in a *See also* section at the end of the entry.
* Smalltalk code snippets should use *tabulation* for source code indentation.
* Smalltalk code snippets should be highlighted using this format:


<pre>```Smalltalk
 Code
```</pre>

## Edit a page

If you see some typo, wrong informations or missing informations you can report it in the issues or you can also edit the document yourself and create a pull request.

Creating a PR is as easy as clicking on the Edit (pen) button, updating the document and propose the changes.

![Gif showing how to edit a page](Resources/EditPage.gif)

## Add a new page

In order to add a page you can just go into the folder of the section where the page should be and use the "Create new file button".

![Gif showing how to add a new page](Resources/CreatePage.gif)

If you need to integrate images in your entry, add them next to the Markdown file with an name following this pattern: `<NameOfThePage>_Image_<Description>.extension`. For example for an image illustrating `Iceberg` in a page called `VCS.md`, the image should be named `VCS_Image_IcebergIllustration.png`.

Once the page is created you need to add it to the [README.md](README.md) in the right section.

> Note: If you have contents to start a page but don't have the time or the knowledge to finish it, it is advised to propose a pull request with the content you have already. Then, one can open issues with the missing sections pointing to the concerned page.

An entry in the README can also have a one short sentense explaining the purpose of the page.

The pages focus mainly on the latest stable Pharo version. This does not mean we refuse contribution on older or development version of Pharo, but those should be complement of the current stable version.

## Deleting, Moving or Renaming a page

**/!\\ We never delete a page. /!\\**

This is a rule in this wiki. What is more annoying than a 404 when we look for documentation?

Instead we have different strategies depending on why we want to delete a page.

### If the content is obsolete

If the content is obsolete, we do not delete the page but we add a note (using `> OBSOLETE : bla`) at the beginning explaining why the guide is obsolete. The guide can be removed from the README. 

### If we want to move a page

If we want to move a page, we can copy it to the new location and let the old page at the original location with an explanation and a link to the new page.

### If we want to split a page

Sometimes a page is too big and would win to be splited. In that case the content can be extracted in multiple pages but the original page should stay and contains an index of the new pages.

### If we want to rename a page

If we want to rename a page, we can copy it with the new name and let the old page at the original location with an explanation and a link to the new page.

## Review content

It is really helpful to get reviews of the wiki's content. This can be achieved in multiple ways:
- Review a Pull Request. Comments, approvals and changes request on pull request will help the intergation of new contents.
- Open issues on existing entries.
- Create a Pull Request to propose enhancements to an existing entry.


================================================
FILE: ExternalProjects/DataStructures/DataFrame.md
================================================
# DataFrame



================================================
FILE: ExternalProjects/Export/Arff.md
================================================
# Arff support in Pharo
To be done, talk about the [Arff parser/generator](https://github.com/juliendelplanque/Arff)


================================================
FILE: ExternalProjects/Export/CSV.md
================================================
# CSV support in Pharo
Currently, Pharo provides one main framework to handle the [CSV format](https://fr.wikipedia.org/wiki/Comma-separated_values): NeoCSV.

## NeoCSV
NeoJSON is actually maintained by Sven Van Caekenberghe on [github](https://github.com/svenvc/NeoCSV).
This section shows some quick examples but there is a great [documentation made by Sven](https://github.com/svenvc/docs/blob/master/neo/neo-csv-paper.md) and a chapter in [Enterprise Pharo (chapter 7)](http://books.pharo.org/enterprise-pharo/).

> NeoCSV provides utilities to map Smalltalk objects to CSV lines, this page does not cover this topic to avoid duplication with the great documentation available in [Sven's documentation](https://github.com/svenvc/docs/blob/master/neo/neo-csv-paper.md) and [Enterprise Pharo (chapter 7)](http://books.pharo.org/enterprise-pharo/). Check it out if you need to use such feature!

### Install
To install NeoCSV, simply execute the following code snippet in a playground:
```Smalltalk
Metacello new
	repository: 'github://svenvc/NeoCSV/repository';
	baseline: 'NeoCSV';
	load
```

### Parse CSV
- From `String`:
```Smalltalk
str := 'id, name
0, Julien
1, Cyril
2, Guillaume
'.
str readStreamDo: [ :s |
	(NeoCSVReader on: s)
		skipHeader;
		addIntegerField;
		addField;
		upToEnd ]
```

- From `Stream`:
```Smalltalk
stream := 'id, name
0, Julien
1, Cyril
2, Guillaume
' readStream.

(NeoCSVReader on: stream)
	skipHeader;
	addIntegerField;
	addField;
	upToEnd
```

- Read from CSV file:
```Smalltalk
'/path/to/file.csv' asFileReference
	readStreamDo: [ :readStream |
		(NeoCSVReader on: readStream)
			skipHeader;
			addIntegerField;
			addField;
			upToEnd ]
```

### Generate CSV
Let `data` be defined as:
```Smalltalk
data := #(
(0 'Julien')
(1 'Cyril')
(2 'Guillaume')).
```

- To generate a CSV `String`:
```Smalltalk
String streamContents: [ :writeStream |
	(NeoCSVWriter on: writeStream)
		writeHeader: #(id name);
		nextPutAll: data ]
```

- To generate CSV on a `Stream`:
```Smalltalk
(NeoCSVWriter on: writeStream)
	writeHeader: #(id name);
	nextPutAll: data
```

- To write a CSV file:
```Smalltalk
'/path/to/file.csv' asFileReference
	writeStreamDo: [ :writeStream |
		(NeoCSVWriter on: writeStream)
 			writeHeader: #(id name);
			nextPutAll: data ]
```


================================================
FILE: ExternalProjects/Export/ESCP.md
================================================
# ESCP support in Pharo
To be done, talk about the [ESCP parser/generator](https://github.com/juliendelplanque/ESCP)


================================================
FILE: ExternalProjects/Export/HTML.md
================================================
# HTML support in Pharo
To be done, talk about HTML parser(s)

- XMLParser-HTML

- Soup ?


================================================
FILE: ExternalProjects/Export/JSON.md
================================================
# JSON support in Pharo
Currently, Pharo provides two main frameworks to handle the [JSON format](https://en.wikipedia.org/wiki/JSON).

This page briefly present these two frameworks and expose their differences to help users to choose the one fitting their needs.

- [STONJSON](#stonjson)
  * [Parse JSON](#parse-json)
  * [Generate JSON](#generate-json)
- [NeoJSON](#neojson)
  * [Install](#install)
  * [Parse JSON](#parse-json-1)
  * [Generate JSON](#generate-json-1)
- [STONJSON v.s. NeoJSON](#stonjson-vs-neojson)
- [JSON Schema](#json-schema)

## STONJSON
STONJSON is the built-in JSON parser available in default Pharo images. It is part of the STON package and its development takes place in Pharo's [github repository](https://github.com/pharo-project/pharo).

### Parse JSON
- From `String`:
```Smalltalk
STONJSON fromString: '{ "foo" : 42.0 }' "a Dictionary('foo'->42.0 )"
```

- From `Stream`:
```Smalltalk
readStream := '{ "foo" : 42.0 }' readStream.
STONJSON fromStream: readStream "a Dictionary('foo'->42.0 )"
```

- Read from JSON file:
```Smalltalk
'/path/to/file.json' asFileReference
	readStreamDo: [ :readStream |
		STONJSON fromStream: readStream ] "a Dictionary('foo'->42.0 )"
```

### Generate JSON
- Let `jsonObject` be defined as:
```Smalltalk
jsonObject := Dictionary new
	at: 'foo' put: 42.0;
	yourself.
```

- To generate a JSON `String`:
```Smalltalk
STONJSON toString: jsonObject "'{""foo"":42.0}'"
```

- To generate JSON on a `Stream`:
```Smalltalk
STONJSON put: jsonObject onStream: writeStream
```

- To write a JSON file:
```Smalltalk
'/path/to/file.json' asFileReference
	writeStreamDo: [ :writeStream |
		STONJSON put: jsonObject onStream: writeStream ]
```

To pretty print JSON, either use `STONJSON>>#toStringPretty:` or `STONJSON>>#put:onStreamPretty:`.

## NeoJSON
NeoJSON is actually maintained by Sven Van Caekenberghe on [github](https://github.com/svenvc/NeoJSON). 
This section shows some quick examples but there is a great [documentation made by Sven](https://github.com/svenvc/docs/blob/master/neo/neo-json-paper.md) and a chapter in [Enterprise Pharo (chapter 8)](http://books.pharo.org/enterprise-pharo/).

### Install
To install NeoJSON, simply execute the following code snippet in a playground:
```
Metacello new
	repository: 'github://svenvc/NeoJSON/repository';
	baseline: 'NeoJSON';
	load
```

### Parse JSON

- From `String`:
```Smalltalk
NeoJSONReader fromString: '{ "foo" : 42.0 }' "a Dictionary('foo'->42.0 )"
```

- From `Stream`:
```Smalltalk
readStream := '{ "foo" : 42.0 }' readStream.
(NeoJSONReader on: readStream) next
```

- Read from JSON file:
```Smalltalk
'/path/to/file.json' asFileReference
	readStreamDo: [ :readStream |
		(NeoJSONReader on: readStream) next ] "a Dictionary('foo'->42.0 )"
```

### Generate JSON
Let `jsonObject` be defined as:
```Smalltalk
jsonObject := Dictionary new
	at: 'foo' put: 42.0;
	yourself.
```

- To generate a JSON `String`:
```Smalltalk
NeoJSONWriter toString: jsonObject "'{""foo"":42.0}'"
```

Pretty:
```Smalltalk
NeoJSONWriter toStringPretty: jsonObject
```

- To generate JSON on a `Stream`:
```Smalltalk
(NeoJSONWriter on: writeStream)
	nextPut: jsonObject
```

Pretty:
```Smalltalk
(NeoJSONWriter on: writeStream)
	prettyPrint: true;
	nextPut: jsonObject.
```

- To write a JSON file:
```Smalltalk
'/path/to/file.json' asFileReference
	writeStreamDo: [ :writeStream |
		(NeoJSONWriter on: writeStream)
			nextPut: jsonObject ]
```

Pretty:
```Smalltalk
'/path/to/file.json' asFileReference
	writeStreamDo: [ :writeStream |
		(NeoJSONWriter on: writeStream)
			prettyPrint: true;
			nextPut: jsonObject ]
```

## STONJSON v.s. NeoJSON

|Property                                        |STONJSON            |NeoJSON               |
|------------------------------------------------|--------------------|----------------------|
|Parse JSON                                      | :white_check_mark: | :white_check_mark:   |
|Generate JSON                                   | :white_check_mark: | :white_check_mark:   |
|Pretty-printing                                 | :white_check_mark: | :white_check_mark:   |
|Built-in                                        | :white_check_mark: | :x:                  |
|Facilities to map JSON objects to Pharo objects | :x:                | :white_check_mark:   |
|Facilities to query JSON objects                | :x:                | :white_check_mark: * |

> *See [this post](http://forum.world.st/How-to-query-a-JSON-tp4948175p4948177.html) from Sven on the mailing list to know how to use this feature implemented in `NeoJSONObject`.

## JSON Schema
JSON Schema allows to describes the structure of JSON objects. It is similar to [XML Schema](https://en.wikipedia.org/wiki/XML_Schema_(W3C)) but for JSON.

A yet incomplete (but working in its scope) implementation of JSON Schema is provided by Zweidenker [on github](https://github.com/zweidenker/JSONSchema).


================================================
FILE: ExternalProjects/Export/XML.md
================================================
# XML support in Pharo
To be done, talk about XML parsers, XML model, XPath implementation, etc...


================================================
FILE: ExternalResources/Community.md
================================================
# Community
This page lists links to external resources created by members of Pharo (and sometimes other smalltalks) community.
Links are ranked in the lexicographic order which means that the position of a link in the list is not representative of the quality of the content.

This page exists for the sake of discoverability of Pharo community.

**We do not take any responsibility for content published in these external resources as we have no control on it.**

- [https://astares.blogspot.com](https://astares.blogspot.com) - Blog related to Pharo in general.
- [https://blog.sebastiansastre.co](https://blog.sebastiansastre.co) - Blog related to Pharo in general.
- [https://clementbera.wordpress.com](https://clementbera.wordpress.com) - Blog related to the Pharo virtual machine and its development.
- [https://endormitoire.wordpress.com/2016/10/03/freewill-in-progress-4/](https://endormitoire.wordpress.com/2016/10/03/freewill-in-progress-4/) - Blog related to Pharo in general.
- [https://fuhrmanator.github.io](https://fuhrmanator.github.io) - Blog related to Moose and Pharo in general but not only.
- [https://masteringobjects.wordpress.com](https://masteringobjects.wordpress.com) - Blog related to Pharo development.
- [https://medium.com/@i.oleks](https://medium.com/@i.oleks) - Blog related to Pharo, AI and machine learning.
- [https://medium.com/concerning-pharo](https://medium.com/concerning-pharo) - Blog related to Pharo in general, multiple authors involved.
- [https://medium.com/@juliendelplanque](https://medium.com/@juliendelplanque) - Blog related to Pharo in general.
- [http://www.mirandabanda.org/cogblog/](http://www.mirandabanda.org/cogblog/) - Blog for open-smalltalk-vm.
- [https://thiscontext.com](https://thiscontext.com) - Blog related to caffeine, a smalltalk vm in Javascript and other smalltalk topics.
- [https://80738163270632.blogspot.com/] - Blog related to Pharo in general.


================================================
FILE: General/Baselines.md
================================================
# Baselines

Pharo projects often require a configuration to declare how they should be loaded. This configuration is done via **Baselines**. A baseline defines the packages of the project, their dependencies to each other and to external projects and independent sub-groups that can be loaded.

Adding a baseline to a project has some advantages:
- It makes it easier to load the project
- It makes it easier for others to contribute to your project
- It allows the users of the project to be unaware of the project's dependencies
- It makes explicit the dependencies of the project
- It ensures that packages and dependencies of the project are loaded in the right order

This documentation explains how to write a baseline and how to load the project described by this baseline.

- [Baselines](#baselines)
	- [How to define Baselines](#how-to-define-baselines)
		- [Define packages forming your project](#define-packages-forming-your-project)
		- [Define external dependencies](#define-external-dependencies)
			- [To other remote git projects](#to-other-remote-git-projects)
				- [Depend on a subset of a git project](#depend-on-a-subset-of-a-git-project)
				- [Depends on the same project with different groups](#depends-on-the-same-project-with-different-groups)
			- [To a local git project](#to-a-local-git-project)
			- [To smalltalkhub projects](#to-smalltalkhub-projects)
		- [Groups](#groups)
			- [The default group](#the-default-group)
		- [Pre/post load actions](#prepost-load-actions)
		- [Loads different packages depending on the Pharo version](#loads-different-packages-depending-on-the-pharo-version)
		- [Define custom attributes](#define-custom-attributes)
		- [Loading types](#loading-types)
			- [Linear loading](#linear-loading)
			- [Atomic loading](#atomic-loading)
		- [Full example](#full-example)
	- [How to load a git project using its baseline](#how-to-load-a-git-project-using-its-baseline)
		- [From the playground](#from-the-playground)
			- [Project managed with Git](#project-managed-with-git)
				- [Project from github/gitlab/bitbucket](#project-from-githubgitlabbitbucket)
				- [Project from local repository](#project-from-local-repository)
			- [Project managed with Smalltalkhub](#project-managed-with-smalltalkhub)
			- [Project without repository](#project-without-repository)
			- [Loading groups](#loading-groups)
			- [Conflict, Upgrade and Downgrade resolution](#conflict-upgrade-and-downgrade-resolution)
			- [Manage warnings](#manage-warnings)
		- [From Iceberg](#from-iceberg)
	- [Other features](#other-features)
		- [Metacello lock feature](#metacello-lock-feature)
		- [Metacello get feature](#metacello-get-feature)
		- [Metacello fetch feature](#metacello-fetch-feature)
		- [Metacello record feature](#metacello-record-feature)
		- [Metacello listing feature](#metacello-listing-feature)
	- [See also](#see-also)

## How to define Baselines

The first step to create a baseline is to create a new subclass of `BaselineOf`. In the following example, `MyProject` is to be substituted by the name of your project:

```Smalltalk
BaselineOf subclass: #BaselineOfMyProject
	slots: {  }
	classVariables: {  }
	package: 'BaselineOfMyProject'
```

This class should be in a package separated from other packages' projects. The package holding the baseline **must** have the same name as the baseline. To summarize, `BaselineOfMyProject` class is in the `BaselineOfMyProject` package.

Then, create a method that defines the spec of the project for the commit it will be included in.

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"The main code of the baseline will go here"
		]
```

> The name of this method does not have to be `#baseline:`; however, that is the name that is commonly used. In fact, it is the `<baseline>` pragma which specifies that the method defines the spec of the project.

If your project is stored using a metadataless format (Tonel or FileTree metadataless), which is the default since Pharo 6, you need to add this method to your baseline:

```Smalltalk
projectClass
	^ MetacelloCypressBaselineProject
```

Or, if the project should be loadable in Pharo < 6.1, use this version:

```Smalltalk
projectClass
	^ [ self class environment at: #MetacelloCypressBaselineProject ]
	on: NotFound
	do: [ super projectClass ]
```
> The method is common to all projets using the metadataless format and the class return does not depend on the name of your baseline.

This will allow Metacello to be able to update your project and is needed because the default project class of Metacello used metadata to know if an update was needed.

### Define packages forming your project

To define the packages of the project, send the message `#package:` to the spec with the name of the package as argument.

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests';
				package: 'MyProject-Gui';
				package: 'MyProject-Gui-Tests';
				package: 'MyProject-Examples' ]
```

> Note: Packages are the most atomic entities managed by the baseline. It is not possible to declare entities at the package-tag granularity.

Defining packages is not enough to load them, because some of them might depend on other packages/projects. For example, `MyProject-Tests` needs to be loaded after `MyProject`.

To manage dependencies that are external to a project, see section *[Define external dependencies](#define-external-dependencies)*.

For dependencies between the packages of your project, you can use the message `#package:with:` to give more information to the spec.

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
			do: [
				"Packages"
				spec
					package: 'MyProject';
					package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
					package: 'MyProject-Gui' with: [ spec requires: #('MyProject') ];
					package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
					package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ]
```

The method `#requires:` will define the list of dependencies of a specific package.

Another way to declare requirements is to use the method `#includes:`. This method takes a collection of declarations as a parameter and will notify Metacello that all of them should include the package if they are loaded. This is helpful when defining platform-specific requirements, in case we want one of our packages to come with a platform-dependant package, which is depending on this package. See example in section *[Loads different packages depending on the Pharo version](#loads-different-packages-depending-on-the-pharo-version)*.

### Define external dependencies

Defining external dependencies can be done in different ways depending on where the dependency is hosted.

> To improve readability, I recommend extracting the definitions of dependencies into separate methods.

#### To other remote git projects

To depend on a git project, you can use the method `#baseline:with:`.

```Smalltalk
spec
	baseline: '{BaselineName}'
	with: [ spec repository: '{prefix}://{url}:{owner}/{projectName}:{version}/{subfolder}' ]
```

This snippet should be configured with:

- `{BaselineName}`: The name of the baseline to load (e.g, `'MaterialDesignLite'` to load `BaselineOfMaterialDesignLite`)
- `{prefix}`: This is host-specific:
  - `github` for github
  - `bitbucket` for bitbucket
  - `gitlab` for gitlab
  - `git` for others (and {url} is thus mandatory)
- `{url}`: Base url to the git host. Mandatory when prefix `git` is used, optional for other prefixes (can be useful for self hosted gitlab for example)
- `{owner}`: Name of the user or organization hosting the project
- `{projectName}`: Name of the project
- `{version}`: This parameter is optional (defaults to master). It can be the name of a branch, a tag like `'v1.2.0'` or `'v1.x.x'`, or a the SHA of a commit
- `{subfolder}`: This parameter is optional in case the code is not at the root of the project. It should point to the sub-folder containing the code

Example:

```Smalltalk
spec
	baseline: 'MaterialDesignLite'
	with: [ spec repository: 'github://DuneSt/MaterialDesignLite:v1.x.x/src']
```

##### Depend on a subset of a git project

Some projects can defines `groups` in their baselines. They are subsets of the project that can be loaded independently.
The previous snippet can also be customized to load only a specific group of the dependency like this:


```Smalltalk
spec
	baseline: 'MaterialDesignLite'
	with: [
		spec
		loads: #('Extensions');
		repository: 'github://DuneSt/MaterialDesignLite:v1.x.x/src'
	]
```

Once the dependency is defined, add `BaselineName` to the list of the required dependencies of the package depending on it.

Example:

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Dependencies"
			self materialDesignLite: spec.

			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject' 'MaterialDesignLite') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ].
```

```Smalltalk
materialDesignLite: spec
	spec
		baseline: 'MaterialDesignLite'
		with: [
			spec  
				loads: #('Extensions');
				repository: 'github://DuneSt/MaterialDesignLite:v1.x.x/src'
		]
```

##### Depends on the same project with different groups

In some cases your project might depend on an external project, but two packages of your project depend on different groups of this external project.

You can use the message `#project:copyFrom:with:` to create a new dependency spec.

```Smalltalk
materialDesignLite: spec
	spec
		baseline: 'MaterialDesignLite' with: [ spec repository: 'github://DuneSt/MaterialDesignLite:v1.x.x/src' ];
		project: 'MaterialDesignLiteExtensions' copyFrom: 'MaterialDesignLite' with: [ spec loads: #('Extensions') ]
```

Then you can use the new project name in the specification of dependencies.

Example:

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Dependencies"
			self materialDesignLite: spec.

			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject' 'MaterialDesignLiteExtensions') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests' 'MaterialDesignLite' "We load the version containing MDL tests for our tests only") ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ].
```

```Smalltalk
materialDesignLite: spec
	spec
		baseline: 'MaterialDesignLite' with: [ spec repository: 'github://DuneSt/MaterialDesignLite:v1.x.x/src' ];
		project: 'MaterialDesignLiteExtensions' copyFrom: 'MaterialDesignLite' with: [ spec loads: #('Extensions') ]
```

#### To a local git project

Sometimes we do not have access to a network, so we want to define dependencies to local git repositories.

This works like in the previous section, but with this repository format:

```Smalltalk
spec
	baseline: 'MaterialDesignLite'
	with: [ spec repository: 'gitlocal://full/path/to/repository' ]
```

#### To smalltalkhub projects

Depending on a [Smalltalkhub](http://smalltalkhub.com) project is done via `#project:with`.

```Smalltalk
spec
	project: '{DependencyName}'
	with: [ spec
		className: #ConfigurationOf{ConfigurationName};
		versionString: #'{Version}';
		repository: 'http://smalltalkhub.com/mc/{owner}/{repositoryName}/main/' ]
```

The snippet should be configured with:

- `{DependencyName}`: It can be anything from your packages, groups and other dependencies names. It will be used to define dependency to this project in your packages/groups
- `{ConfigurationName}`: It is the name of the configuration you wish to reference
- `{Version}`: Name of the version you wish to reference. It can be something like `'development'`, `'stable'`, `'release1'`, `'1.2.6'`, `'1.0-baseline'`, etc.
- `{owner}`: Name of the team or user hosting the project
- `{repositoryName}`: Name of the repository on SmalltalkHub

Example:

```Smalltalk
spec
	project: 'Magritte3'
	with: [ spec
		className: #ConfigurationOfMagritte3;
		versionString: #'release3';
		repository: 'http://smalltalkhub.com/mc/Magritte/Magritte3/main/' ]
```

As for git-hosted repositories, you can ask for a specific group:

```Smalltalk
spec
	project: 'Magritte3'
	with: [ spec
		className: #ConfigurationOfMagritte3;
		versionString: #'release3';
		loads: #('Seaside');
		repository: 'http://smalltalkhub.com/mc/Magritte/Magritte3/main/' ]
```

You can now use the dependency names to add the project as a dependency of your packages.

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Dependencies"
			self magritte3: spec.

			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject' 'Magritte3') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ].
```

```Smalltalk
magritte3: spec
	spec
		project: 'Magritte3'
		with: [ spec
			className: #ConfigurationOfMagritte3;
			versionString: #'release3';
			loads: #('Seaside');
			repository: 'http://smalltalkhub.com/mc/Magritte/Magritte3/main/' ]
```

### Groups

Sometimes we don't want to load the full project, but just a sub part, e.g.:

- Only the model of a project is needed without the UI (for example to build an alternative UI)
- Only the core of the project is needed without the tests and examples
- The project has some optional modules
- etc.

To manage such cases, baselines have the concept of a `Group`. A group is a loadable spec containing only a sub part of the project.

They can be declared with the `#group:with:` message. The second parameter defines the content of the group. The content can either be a package name, a dependency name, or even another group name.

Example:

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ].

			"Groups"
			spec
				group: 'Model' with: #('MyProject');
				group: 'Tests' with: #('MyProject-Tests' 'MyProject-Gui-Tests');
				group: 'Gui' with: #('MyProject-Gui');
				group: 'Example' with: #('MyProject-Examples');
				group: 'All' with: #('Model' 'Tests' 'Gui' 'Example')
```

> To load a project with a given group, you can check the section [loading groups](#loading-groups).

#### The default group

Each baseline has a default group named `'default'`. This group includes all the packages and the dependencies declared in the baseline.

When using the message `#load` with Metacello, or when not specifying the group of a dependency, it will load the "default" group.

This group can be redefined to change what will be loaded by default in a project.

Example:

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ].

			"Groups"
			spec
				group: 'default' with: #('Model' 'Gui');
				group: 'Model' with: #('MyProject');
				group: 'Tests' with: #('MyProject-Tests' 'MyProject-Gui-Tests');
				group: 'Gui' with: #('MyProject-Gui');
				group: 'Example' with: #('MyProject-Examples');
				group: 'All' with: #('Model' 'Tests' 'Gui' 'Example')
```

### Pre/post load actions

Baselines provide some hooks to execute some code when loading a project.

Those hooks are:

- `#preLoadDoIt:` which is executed after the code and dependencies are resolved and fetched, but before the code is loaded.
- `#postLoadDoIt:` which is executed when the project finishes loading.

Those methods take a symbol as parameter, which should be the name of a method of the baseline that should be executed by the hook.

Those methods can take two optional parameters:

- A Metacello loader containing information on the current project to load
- A Metacello spec containing information on the project spec

Example:

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			spec preLoadDoIt: #'preload:package:'.
			spec postLoadDoIt: #'postload:package:'.

			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ]
```

```Smalltalk
preload: loader package: packageSpec

	Transcript crLog: 'The fetch was finished. Now let''s load the project'
```

```Smalltalk
postload: loader package: packageSpec

	Transcript crLog: 'Project loaded!'
```

### Loads different packages depending on the Pharo version

It might be useful to load some packages in specific Pharo versions only. For example, if we have a compatibility package for Pharo 6, we do not want to load it in Pharo 7.

This is possible with the different spec attributes.

Up until now we defined everything in a spec for `#common`, which applies to all versions of Pharo. But it's possible to define a spec for specific Pharo versions or even other Smalltalk environments.

We can add in the baseline a special `#for:do:` command taking as parameter a specific attribute.

Every Pharo version contains some default attributes. For a Pharo version X.Y we have:

- `#pharo`
- `#pharoX.x`
- `#pharoX.Y.x`

For example for Pharo 6.1:

- `#pharo`
- `#pharo6.x`
- `#pharo6.1.x`

Those attributes can be used to define a spec that will be executed only in the images containing the corresponding tags.

Example:

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ].

			spec
				for: #'pharo6.x'
				do: [ spec
					package: 'MyProject' with: [ spec requires: #('MyProject-Pharo6') ];
					package: 'MyProject-Pharo6' ].
			spec
				for: #(#'pharo3.x' #'pharo4.x' #'pharo5.x' #'pharo6.x')
				do: [ spec
					package: 'MyProject' with: [ spec requires: #('MyProject-Pharo3To6') ];
					package: 'MyProject-Pharo3To6' ] ]
```

The `#includes:` method explained in section *[Define packages forming your project](#define-packages-forming-your-project)* is often useful when dealing with platform-specific requirements. Imagine your package `MyProject` will work in Pharo 6 only if `MyProject-Pharo6` is present, but `MyProject-Pharo6` depends on `MyProject`. This can be resolved like this:

Example:

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ].

			spec
				for: #'pharo6.x'
				do: [ spec
					package: 'MyProject' with: [ spec includes: #('MyProject-Pharo6') ];
					package: 'MyProject-Pharo6' with: [ spec requires: #('MyProject') ] ].
			spec
				for: #(#'pharo3.x' #'pharo4.x' #'pharo5.x' #'pharo6.x')
				do: [ spec
					package: 'MyProject' with: [ spec requires: #('MyProject-Pharo3To6') ];
					package: 'MyProject-Pharo3To6' ] ]
```

### Define custom attributes

On top of attributes from Pharo, it's also possible to define our own attributes.

We override the method `#customProjectAttributes` to return the custom attributes depending on the environment.

For example:

```Smalltalk
customProjectAttributes
	Smalltalk os isMacOS ifTrue: [ ^ #(#MacOS) ].
	Smalltalk os isUnix ifTrue: [ ^ #(#Unix) ].
	Smalltalk os isWindows ifTrue: [ ^ #(#Windows) ]
```

Then they can be used in the baseline.

```Smalltalk
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests') ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ] ].

			spec
				for: #(#'MacOS' #'Unix') do: [
					self osSubprocess: spec.
					spec package: 'MyProject' with: [ spec requires: #('OSSubprocess') ] ];
				for: #'Windows' do: [
					self processWrapper: spec.
					spec package: 'MyProject' with: [ spec requires: #('ProcessWrapper') ] ]
```

```Smalltalk
osSubprocess: spec
	spec
		baseline: 'OSSubprocess'
		with: [ spec repository: 'github://pharo-contributions/OSSubprocess:v1.0.1/repository' ]
```

```Smalltalk
processWrapper: spec
	spec 
		configuration: 'ProcessWrapper'
		with: [
			spec
				versionString: '1.2';
				repository: 'http://smalltalkhub.com/mc/hernan/ProcessWrapper/main' ]
```

### Loading types

Baselines support different loading types. The loading types define how Metacello loads the project.

#### Linear loading

By default, a baseline uses linear loading, which means packages are loaded one by one with their requirements loaded before them.

#### Atomic loading

This load type forces Metacello to load the full project in an atomic load. This is useful when a project has cyclic dependencies that cannot be resolved. For example it's useful to do an atomic load of Pharo's Kernel and Collections, since they depend on each other.

To define atomic loading, override the method `#project`:

```Smalltalk
project
	^ super project
		loadType: #atomic;
		yourself
```

### Full example

Here is an example with all previous features illustrated:

```Smalltalk
"baseline"
baseline: spec
	<baseline>
	spec
		for: #common
		do: [
			spec preLoadDoIt: #'preload:package:'.
			spec postLoadDoIt: #'postload:package:'.

			"Dependencies"
			self materialDesignLite: spec.

			"Packages"
			spec
				package: 'MyProject';
				package: 'MyProject-Tests' with: [ spec requires: #('MyProject') ];
				package: 'MyProject-Gui' with: [ spec requires: #('MyProject' 'MaterialDesignLiteExtensions' 'Magritte3') ];
				package: 'MyProject-Gui-Tests' with: [ spec requires: #('MyProject-Tests' 'MaterialDesignLite' "We load the version containing MDL tests for our tests only") ];
				package: 'MyProject-Examples' with: [ spec requires: #('MyProject-Gui') ].

			"Groups"
			spec
				group: 'Model' with: #('MyProject');
				group: 'Tests' with: #('MyProject-Tests' 'MyProject-Gui-Tests');
				group: 'Gui' with: #('MyProject-Gui');
				group: 'Example' with: #('MyProject-Examples');
				group: 'All' with: #('Model' 'Tests' 'Gui' 'Example') ].

			spec
				for: #'pharo6.x'
				do: [ spec
					package: 'MyProject' with: [ spec includes: #('MyProject-Pharo6') ];
					package: 'MyProject-Pharo6' with: [ spec requires: #('MyProject') ] ].

			spec
				for: #(#'pharo3.x' #'pharo4.x' #'pharo5.x' #'pharo6.x')
				do: [ spec
					package: 'MyProject' with: [ spec requires: #('MyProject-Pharo3To6') ];
					package: 'MyProject-Pharo3To6' ] ].

			spec
				for: #(#'MacOS' #'Unix') do: [
					self osSubprocess: spec.
					spec package: 'MyProject' with: [ spec requires: #('OSSubprocess') ] ].

			spec
				for: #'Windows' do: [
					self processWrapper: spec.
					spec package: 'MyProject' with: [ spec requires: #('ProcessWrapper') ] ]
```

```Smalltalk
projectClass
	^ MetacelloCypressBaselineProject
```

```Smalltalk
"dependencies"
materialDesignLite: spec
	spec
		baseline: 'MaterialDesignLite' with: [ spec repository: 'github://DuneSt/MaterialDesignLite:v1.x.x/src' ];
		project: 'MaterialDesignLiteExtensions' copyFrom: 'MaterialDesignLite' with: [ spec loads: #('Extensions') ]
```

```Smalltalk
"dependencies"
magritte3: spec
	spec
		project: 'Magritte3'
		with: [ spec
			className: #ConfigurationOfMagritte3;
			versionString: #'release3';
			loads: #('Seaside');
			repository: 'http://smalltalkhub.com/mc/Magritte/Magritte3/main/' ]
```

```Smalltalk
"dependencies"
osSubprocess: spec
	spec
		baseline: 'OSSubprocess'
		with: [ spec repository: 'github://pharo-contributions/OSSubprocess:v1.0.1/repository' ]
```

```Smalltalk
"dependencies"
processWrapper: spec
	spec
		configuration: 'ProcessWrapper'
		with: [
			spec
				versionString: '1.2';
				repository: 'http://smalltalkhub.com/mc/hernan/ProcessWrapper/main' ]
```

```Smalltalk
"accessing"
customProjectAttributes
	Smalltalk os isMacOS ifTrue: [ ^ #(#MacOS) ].
	Smalltalk os isUnix ifTrue: [ ^ #(#Unix) ].
	Smalltalk os isWindows ifTrue: [ ^ #(#Windows) ]
```

```Smalltalk
"actions"
preload: loader package: packageSpec

	Transcript crLog: 'The fetch was finished. Now let''s load the project'
```

```Smalltalk
"actions"
postload: loader package: packageSpec

	Transcript crLog: 'Project loaded!'
```

```Smalltalk
"accessing"
project
	^ super project
		loadType: #atomic;
		yourself
```

## How to load a git project using its baseline

When you have a project with a *Baseline*, it is possible to load it in a Pharo image if the project is compatible with the Pharo version.

Here we explain how to load a git project via its baseline.

### From the playground

The first way to load a project is to create a *Metacello* request programmatically and to execute it. This request looks like this:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.x.x' path: 'src';
	baseline: 'MaterialDesignLite';
	load
```

Note the three steps:

1. Create a new Metacello request
2. Configure it (declare the repository of the project, specify the version, the baseline, optional options...)
3. Launch the loading

To configure the request, some options are necessary and some are optional. We cover in the next two sub sections how to configure the loading of a project hosted via Monticello and git, and then we detail optional parameters.

#### Project managed with Git

To load a project from git you need to execute an expression like this:

```Smalltalk
Metacello new
	repository: {repository};
	baseline: {baselineName};
	load
```

This command has two parameters:

- `repository` defining the location of the git project, the version of the project to load and the subdirectory in which the project is stored.
- `baselineName` is the name of the baseline to load. For example to load the `MaterialDesignLite` project, the baseline name is `MaterialDesignLite` to load the project with `BaselineOfMaterialDesignLite`.

The repository parameter is a string that can take different forms depending on if the project is local or hosted remotely.

##### Project from github/gitlab/bitbucket

The repository parameter to load a project from github/gitlab/bitbucket takes this form:

`{prefix}://{optionalHostname}:{owner}/{projectName}:{version}/{subFolder}`

This snippet should be configured with:

- `{prefix}`: This is host-specific:
  - `github` for github
  - `bitbucket` for bitbucket
  - `gitlab` for gitlab
- `{optionalHostname}`: Optional server host, for private git servers
- `{owner}`: Name of the user or organization hosting the project
- `{projectName}`: Name of the project
- `{version}`: This parameter is optional, and it defaults to master. It can be the name of a branch, a tag like `'v1.2.0'` or `'v1.x.x'`, or a the SHA of a commit
- `{subfolder}`: This parameter is optional in case the code is at the root of the project. It should point to the sub-folder containing the code.

Example: loading from Github.

```Smalltalk
Metacello new
	repository: 'github://DuneSt/MaterialDesignLite:v1.x.x/src';
	baseline: 'MaterialDesignLite';
	load
```

Example: loading from a private Gitlab host.

```Smalltalk
Metacello new 
	baseline: 'Ghost';
	repository: 'gitlab://gitlab.inria.fr:RMOD/Ghost';
	load
```

Metacello also comes with some syntactic sugar to define the repository to github or bitbucket:

- *Github*: `Metacello>>githubUser:project:commitish:path:`
- *Bitbucket*: `Metacello>>bitbucketUser:project:commitish:path:`

Example:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'master' path: 'src';
	baseline: 'MaterialDesignLite';
	load
```

##### Project from local repository

To load a project from a local repository you can use this form to declare the repository:

`'{prefix}://{full/path/to/repository}/{subFolder}'`

This snippet should be configured with:

- `{prefix}`: This is specific to the file format:
  - `filetree` for a Filetree project
  - `tonel` for a Tonel project
- `{full/path/to/repository}`: is the path to the project on the file system
- `{subfolder}`: This parameter is optional in case the code is at the root of the project. It should point to the subfolder containing the code.

Example:

```Smalltalk
Metacello new
	repository: 'tonel://C:\Users\Cyril\GitRepositories\Native-Browser\src';
	baseline: 'NativeBrowser';
	load
```

#### Project managed with Smalltalkhub

To load a project from Smalltalkhub you need to execute an expression like this:

```Smalltalk
Metacello new
	repository: 'http://smalltalkhub.com/mc/{owner}/{repositoryName}/main';
	configuration: {configurationName};
	version: {version};
	load
```

This command has two parameters:

- `owner`: Name of the team or user hosting the project
- `repositoryName`: Name of the repository on SmalltalkHub
- `configurationName` is the name of the configuration to load. For example to load the `MaterialDesignLite` project, the baseline name is `MaterialDesignLite` to load the project with `BaselineOfMaterialDesignLite`.
- `{version}`: Name of the version you wish to reference. It can be something like `'development'`, `'stable'`, `'release1'`, `'1.2.6'`, `'1.0-baseline'`, etc.

Example:

```Smalltalk
Metacello new
	repository: 'http://smalltalkhub.com/mc/Seaside/Seaside31/main';
	configuration: 'Seaside3';
	version: #stable;
	load
```

You can also use `Metacello>>smalltalkhubUser:project:`:

```Smalltalk
Metacello new
	smalltalkhubUser: 'Seaside' project: 'Seaside31';
	configuration: 'Seaside3';
	version: #stable;
	load
```

#### Project without repository

It is possible to use Metacello without specifying any repository. This can be useful for defining all project dependencies in a baseline and then loading them with Metacello.

```Smalltalk
Metacello new
	baseline: #TinyBlog;
	load
```

#### Loading groups

Sometimes we want to load only specific groups of a project. This can be done be replacing the `load` selector by `load:`.

The `load:` selector takes a string or a collection of strings as parameter. Each string represents a group name from the baseline.

Examples:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'master' path: 'src';
	baseline: 'MaterialDesignLite';
	load: 'Extensions'
```

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'master' path: 'src';
	baseline: 'MaterialDesignLite';
	load: #('Extensions' 'Widgets')
```

#### Conflict, Upgrade and Downgrade resolution

Sometimes there can be conflicts, updates or downgrades while loading a project.

For example, imagine in an image the project `ProjA` at version v1.0.0. We want to load our project `ProjB` that depends on `ProjA` version v2.0.0., `ProjC` version v1.0.0, and `ProjD` that loads also `ProjC` version v2.0.0.

If we load `ProjB` in those conditions, we will have two problems:

- The update of `ProjA` from v1.0.0 to v2.0.0
- A conflict between `ProjC` v1.0.0 and v2.0.0

To manage conflicts we can use the options `onConflict:`, `onUpgrade:` and `onDowngrade:`.

Example:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'master' path: 'src';
	baseline: 'MaterialDesignLite';
	onConflict: [ :ex | ex useIncoming ];
	onUpgrade: [ :ex | ex useIncoming ];
	onDowngrade: [ :ex | ex useLoaded ];
	load
```

A last conflicting situation happens if Pharo includes a project in the default distribution and you want to load a new version. To manage this case you have the `ignoreImage` option.

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'master' path: 'src';
	baseline: 'MaterialDesignLite';
	onConflict: [ :ex | ex useIncoming ];
	onUpgrade: [ :ex | ex useIncoming ];
	onDowngrade: [ :ex | ex useLoaded ];
	ignoreImage;
	load
```

Here is a last example of conflict management. The Pharo community was previously on a version control system called Monticello. Most of the community has now migrated to GitHub. Some of the projects exist on Smalltalkhub (managed with Monticello) and on GitHub. It's not unusual to have conflict between the two.

Here is a little script that loads the version managed with git when the project name is the same:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'master' path: 'src';
	baseline: 'MaterialDesignLite';
	onConflict: [ :ex :a :b | a projectName = b projectName ifTrue: [ a projectSpec isBaselineOfProjectSpec ifTrue: [ ex useLoaded ] ifFalse: [ ex useIncoming ] ] ifFalse: [ ex resume ] ];
	load
```

#### Manage warnings

In some cases a project has problems during the loading, for example, if a package loaded is missing a dependency. When this happen, Metacello will raise a warning. Most of the time the projects can still work, at least partially. If you do not want Metacello to open a warning, you can log them instead. To enable this option you can use the `onWarningLog` or `onWarning:` options.

Examples:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'master' path: 'src';
	baseline: 'MaterialDesignLite';
	onWarning: [ :ex | Transcript crShow: ex ];
	load
```

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'master' path: 'src';
	baseline: 'MaterialDesignLite';
	onWarningLog;
	load
```

### From Iceberg

In Pharo 7 a new tool to manage git repositories was introduced: *Iceberg*. This tool allows the developer to load a project via a user interface.

The first step is to add your git project to Iceberg. Then right-click on the project name to access a `Metacello` sub-menu to load the project.

![Interface of Iceberg to load a project](Baselines_Image_LoadBaselineViaIceberg.png?raw=true "Interface of Iceberg to load a project")

## Other features

This section covers other features of baselines and Metacello.

### Metacello lock feature

In the normal course of loading and upgrading, you want the correct version of dependent projects loaded. However, there are some special cases where automatic upgrading isn't desirable:

- You may be actively developing a particular version of a project and you don't want the project upgraded (or downgraded) out from under you.
- You may be working with a git checkout of a project and you want to continue using the git checkout.
- You may not want to have particular projects upgraded automatically.

The `lock` command forces a particular version.

Example:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.1.0' path: 'src';
	baseline: 'MaterialDesignLite';
	lock
```

This example will lock the project MaterialDesignLite to version v1.1.0.

You can check the list of locked projects via those snippets:

```Smalltalk
Metacello registry locked. "Return the list of locked projects from the Metacello registry"

Metacello image locked. "Return the list of locked projects loaded in the image."
```

If you wish to unlock a project, you can use the `unlock` message.

Example:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.1.0' path: 'src';
	baseline: 'MaterialDesignLite';
	unlock
```

During the loading of a project you can also do some specific actions when you encounter a lock. For this you can use the `onLock:` message.

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.1.0' path: 'src';
	baseline: 'MaterialDesignLite';
	onLock: [ :ex :loaded :incoming | loaded baseName = 'myProject' ifTrue: [ ex break ] ifFalse: [ ex honor ] ];
	load
```

### Metacello get feature

Metacello includes a command to load the baseline of a project into the image. This is useful in two cases:

- You want to load only the baseline of the project
- You already have an obsolete baseline in your image and you want to update it before loading the project

To do that you can use the `get` command.

Example:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.x.x' path: 'src';
	baseline: 'MaterialDesignLite';
	get
```

### Metacello fetch feature

The fetch command downloads all of the packages without loading them. This includes the packages of the project but also their dependencies.

Example:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.x.x' path: 'src';
	baseline: 'MaterialDesignLite';
	fetch
```

You can also specify a group:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.x.x' path: 'src';
	baseline: 'MaterialDesignLite';
	fetch: #('Extensions' 'Widgets')
```

The fetch command duplicates what the load command would do, which means if a package is already loaded in the image, it will not be fetched. To fetch packages regardless of what is loaded in the image, use the `ignoreImage` option:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.x.x' path: 'src';
	baseline: 'MaterialDesignLite';
	ignoreImage;
	fetch
```

### Metacello record feature

The `record` command performs the same function as the `fetch` command, without actually downloading any files. As a consequence, it can give you a quick report of what packages will be loaded into your image. The recording will be produced in the `Transcript` (cmd + o + t).

Example:

```Smalltalk
Metacello new
	githubUser: 'DuneSt' project: 'MaterialDesignLite' commitish: 'v1.x.x' path: 'src';
	baseline: 'MaterialDesignLite';
	record
```

### Metacello listing feature

The `list` command lists projects in the image or Metacello registry:

```Smalltalk
Metacello image
	baseline: [ :spec | true "spec name beginsWith: 'Seaside'" ];
	list
  
Metacello registry
	baseline: [ :spec | true "spec name beginsWith: 'Seaside'" ];
	list
```

This command needs to be inspected to see the list.

## See also

- Deep into pharo: [Chapter 9, Managing Projects with Metacello](http://files.pharo.org/books-pdfs/deep-into-pharo/2013-DeepIntoPharo-EN.pdf)
- [Metacello documentation](https://github.com/Metacello/metacello/tree/master/docs)


================================================
FILE: General/CJKCharacter.md
================================================
# Using CJK (Chinese, Japanese, and Korean) characters

Pharo's default font settings for code (Source Code Pro) and UI (Source Sans Pro) are unable to handle [CJK characters](https://en.wikipedia.org/wiki/CJK_characters), this page explains how to display them properly in Pharo.

![Preview string for chinese characters under Source Code Pro](CJKCharacter_Screenshot_1.png)

Operating systems may come with fonts that support those characters but they are usually not monospaced which is not good for displaying code. If one need to display CJK characters in Pharo, it is recommended to install a monospace font which also covers CJK characters. Some of them are [`Noto Sans Mono CJK`](https://www.google.com/get/noto/) , `Microsoft YaHei Mono`, [`WenQuanYi Zen Hei Mono`](http://wenq.org).

Note one must enable the option `Update fonts at startup` first and restart Pharo to make the font selection dialog below show all available fonts:
1. Select menu `Pharo` -> `Settings` to show the `Settings Browser`.
2. Enable `Appearance` -> `Use Free type...` -> `Update fonts at startup`, this can be disabled later after one changes the fonts.

![Preview string for chinese characters under Microsoft YaHei Mono](CJKCharacter_Screenshot_2.png)

Note that on Windows 10, one may need to manually copy font files to `C:\Windows\Fonts\`.

Here is a code sample:

```Smalltalk
StandardFonts 
	defaultFont: (LogicalFont familyName: 'Noto Sans CJK SC' pointSize: 9);
	codeFont: (LogicalFont familyName: 'Microsoft YaHei Mono' pointSize: 10);
	listFont: (LogicalFont familyName: 'Noto Sans CJK SC' pointSize: 9);
	menuFont: (LogicalFont familyName: 'Noto Sans CJK SC' pointSize: 9);
	buttonFont: (LogicalFont familyName: 'Noto Sans CJK SC' pointSize: 9);
	windowTitleFont: (LogicalFont familyName: 'Noto Sans CJK SC' pointSize: 10);
	balloonFont: (LogicalFont familyName: 'Noto Sans CJK SC' pointSize: 8);
	haloFont: (LogicalFont familyName: 'Noto Sans CJK SC' pointSize: 8).
```

## Related links:

https://www.samadhiweb.com/blog/2019.02.22.windows.multilingual.html  
http://forum.world.st/Japanese-Fonts-td4928056.html  
http://forum.world.st/im-using-pharo-7-with-linux-env-but-cannot-input-korean-td5095342.html


================================================
FILE: General/CJKInputMethod.md
================================================
# Using CJK (Chinese, Japanese, and Korean) Input Method

It's possible to use CJK input method in Pharo. Tested under Pharo8 on macOS, Linux and Windows.

## Linux

On linux, you need add `-compositioninput` in VM args and make sure you are using Fcitx5.


================================================
FILE: General/CodingConventions.md
================================================
# Coding conventions

Pharo is full of implicit coding conventions. 

This page aims to document all those conventions to help newcomers write Pharo code as per the community's idioms.

## Tests conventions

Pharo has some conventions when it comes to tests. This section covers those.

**Package name**

It is preferred to store tests in a separate package rather than in the package of the tested classes.
The name of this package should be `NameOfOriginalPackage-Tests`.

For example, if one wants to add tests to `Material-Design-Lite-Core`, the tests should be in a package called `Material-Design-Lite-Core-Tests`.

**Class name**

Tests classes (subclasses of `TestCase`) should end with the suffix `Test` (and not `Tests` because a test class is a test case).

In the case of unit tests, the name of the class should be `MyClassTest`. For example, if one wants to add unit tests of `MDLButton`, the test class will be named `MDLButtonTest`.

**Method name**

Test method names in Pharo need to be prefixed with `test`. This is the way the test framework recognizes them as test methods. 

In case of a unit test on a method of the tested class, the name should be prefixed by `test` followed by the name of the method to test.

For example:
- The unit test for `#click` will be named `#testClick`
- The unit test for `#clickElement:` will be named `#testClickElement`
- The unit test for `#clickElement:withShiftPressed:` will be named `#testClickElementWithShiftPressed`

By doing that, a new icon next to your actual method name will appear in the system browser.
This icon allows one to launch the unit test of the method via a click.


================================================
FILE: General/CoolSnippets.md
================================================
# Cool Snippets

This file contains snippets of code that can be useful sometimes.

- [Download a file with a progress bar](#download-a-file-with-a-progress-bar)
- [Bench and profile a project from the tests](#bench-and-profile-a-project-from-the-tests)
- [Automatic transformation of Pharo's methods source code](#automatic-transformation-of-pharo-s-methods-source-code)
- [Browse all available icons](#browse-all-available-icons)
- [Rename programatically methods](#rename-programatically-methods)
- [Get all senders/implementors of a selector](#get-all-sendersimplementors-of-a-selector)
- [Find dependencies on a package](#find-dependencies-on-a-package)
- [Embed an image (picture) into Pharo](#embed-an-image-picture-into-pharo)

## Download a file with a progress bar

```Smalltalk
| outputFileName url |
outputFileName := './pharoLogo.png'.
outputFileName asFileReference ensureDelete.
url := 'http://files.pharo.org/media/logo/logo-flat.png' asZnUrl.
[ :bar | 
	bar title: 'Download: ' , url asString , ' to ' , outputFileName.
	[ ZnClient new
		url: url;
		signalProgress: true;
		downloadTo: outputFileName ]
		on: HTTPProgress
		do: [ :progress | 
			progress isEmpty ifFalse: [ bar current: progress percentage ].
			progress resume ] ] asJob run
```

## Bench and profile a project from the tests

```Smalltalk
packageSelectionBlock := [ :e | e name beginsWith: 'Spec' ].
testSuite := TestSuite new.
	
((RPackageOrganizer default packages select: packageSelectionBlock) flatCollect: #classes) select: [ :e | e inheritsFrom: TestCase ] thenDo: [ :e | e addToSuiteFromSelectors: testSuite ].

"Bench the test suite"	
[ testSuite run ] bench.

"Profile the test suite"
TimeProfiler spyOn: [ testSuite run ]

```

## Automatic transformation of Pharo's methods source code
During software maintenance, being able to transform source code automatically can be handy. It can be done easily in Pharo using the built-in code rewriting engine.

For example, let's say that we want to replace the occurences of `#symbolToReplace` symbol with occurences of `#replacedSymbol` in the following method:

```Smalltalk
ExampleCodeTransformation>>#methodToTransform
	1 + 1 = 2
		ifTrue: [ ^ #symbolToReplace ].

	^ #symbolToReplace , #symbolNotToReplace
```

It can be done easily using the following code snippet:

```Smalltalk
compiledMethod := ExampleCodeTransformation >> #methodToTransform.

ast := compiledMethod parseTree.

"Here we select only nodes holding the target symbol and we replace it with a node representing `#replacedSymbol`."
ast allChildren
	select: [ :n | n class = RBLiteralValueNode and: [ n value = #symbolToReplace ] ]
	thenDo: [ :node |
		rewriter := RBParseTreeRewriter new
			replaceTree: node
			withTree: (RBLiteralValueNode value: #replacedSymbol);
			yourself.
		(rewriter executeTree: ast)
			ifTrue: [ node replaceWith: rewriter tree ] ].
		
"Serialize the new AST as Pharo source code."
rewrittenSourceCode := (BIConfigurableFormatter format: ast).

"Recompile the method with transformed source code."
ExampleCodeTransformation compile: rewrittenSourceCode
```

## Browse all available icons
The following code snippet opens an inspector in which the 'Icons' tab allows to browse all icons available in the image.

```
Smalltalk ui icons inspect
```

To get a specific icon, use `#iconNamed:` method as follow:

```
Smalltalk ui icons iconNamed: #arrowUp
```

## Rename methods programatically

In this section we will present a code snippet to rename all methods of a class by replacing one substring with another. First, we find all methods of a given class with names that contain a substring `A`, then we rename those methods to replace `A` with another substring `B`.

```Smalltalk
"Class in which we want to rename the methods"
class := EpApplyPreviewerTest.
"Substring to replace"
from := 'With'.
"Substring to use"
to := 'Without'.

class methods
	select: [ :method | method selector includesSubstring: from ]
	thenDo: [ :method | 
		| permutationMap |
		"We want to keep the arguments in the same order"
		permutationMap := method numArgs = 0 ifTrue: [ #() ] ifFalse: [ (1 to: method numArgs) asArray ].
		
		(RBRenameMethodRefactoring
			renameMethod: method selector
			in: class
			to: (method selector copyReplaceAll: from with: to)
			permutation: permutationMap) execute ]
```

> Be careful, this will also rename the senders of those methods and if you have two methods with the same name in the image, it might badly rename some of them. Use this only on methods with unique names.

## Get all senders/implementors of a selector
The selector of a method is kind of the equivalent of the signature of a method or function in other programming languages.
However, since Pharo is dynamically typed, this selector is only the name of the method, without the parameters.
For example, the selector of the method below is `#name:`

```
Example>>name: aString
	name := aString
```

For a given `CompiledMethod` in the system, its selector is accessible via `#selector` message.

```
(Object>>#yourself) selector. "#yourself"
```

### Senders
To get all the senders of a selector accross the image, simply call `#senders` on the selector:

```
#yourself senders
```

### Implementors
To get all `CompiledMethod`s implementing a method having a selector, simply call `#implementors` on the selector:

```
#yourself implementors
```

## Find dependencies on a package

In Pharo it is easy to find the dependencies of one package through the `Dependency Analyzer`, but there is no tool to browse the dependencies *on* a single package. 

It is possible to do it programatically via this snippet:

```Smalltalk
report := DADependencyChecker new computeImageDependencies. "This might take some time but it will run in background"
report knownDependantsOf: 'Epicea' "Replace Epicia by the name of your package."
```

## Embed an image (picture) into Pharo
If you want to add an image into Pharo, you will need to import it
```Smalltalk
ImageReadWriter formFromFileNamed: 'test.png'
```
and you may store it into the image for further reuse. This is achieved by encoding the image into a base 64 String. Then, the String can be stored in a method.
```Smalltalk
(Base64MimeConverter mimeEncode: 'test.png' asFileReference binaryReadStream) contents
```
Let's say we store the image base64 String in `Foo>>#image`. To materialize a Form from this image, you can do:
```Smalltalk
Form fromBinaryStream: Foo image base64Decoded asByteArray readStream
```
Here is a shortcut available since Pharo 8.0:
```Smalltalk
Form fromBase64String: Foo image
```


================================================
FILE: General/DeployYourPharoApplication.md
================================================
# How to deploy a Pharo application

*This guide has for purpose to help developpers deploying a Pharo application. If something is missing to you, do not hesitate to open an issue.*

**This guide is first written for Pharo 7. Some parts will not work in Pharo 6 and earlier.**

- [How to deploy a Pharo application](#how-to-deploy-a-pharo-application)
  * [Cruiser: A tool for app deployment?](#cruiser)
  * [Clean your image before deployment](#clean-your-image-before-deployment)
  * [Sources obfuscation](#sources-obfuscation)
  * [Change the logo and window title of the application](#change-the-logo-and-window-title-of-the-application)
  * [Deploy a Seaside application with Nginx](#deploy-a-seaside-application-with-nginx)

## Cruiser
Cruiser is a tool to package Pharo applications. The idea is to quickly convert an application in a development environment to a production one.
[https://github.com/VincentBlondeau/Cruiser](https://github.com/VincentBlondeau/Cruiser)


## Clean your image before deployment

In this section we explain various ways to clean an image for deployment. All steps are not necessary and the benefits are given in each subsection.

### Clean up the system

A first step is to launch a cleanup of the image. Pharo already contains a system to cleanup divers part of the system by calling the `#cleanUp(:)` method of every class implementing it.

It can be done with this snippet:

```Smalltalk
Smalltalk cleanUp: true except: {} confirming: false
```

The first parameter should be a boolean. If it's value is `true` it will launch a more aggresive cleanup and this will destroy resources, change sets, etc.
The second parameter allows the developper to exclude some classes of the cleanup by passing an array containing all the classes that should not execute their cleanup.

### Ensure logins are removed from the image

During the deployment of an application it might be a good idea to remove all login informations from the image.

In order to do that you can execute this script:

```Smalltalk
| store |

"Remove all repositories from Monticello VCS"
MCRepositoryGroup allSubInstancesDo: [ :group | group repositories do: [ :repo | group removeRepository: repo ] ].

"Remove projects and credentials from Git VCS (Tested in Pharo 7)"
IceRepository registry removeAll.
store := IceCredentialStore current.
store allCredentials do: [ :each | each removeFrom: store ]
```

With this step done all the credentials should be removed from the image if you do not use an external project from Pharo that store some credentials.

### Close all windows

While deploying an application you might want to ensure every Morph is closed (to remove the Pharo welcome window for example).

This can directly be done via the command:

```Smalltalk
World closeAllWindowsDiscardingChanges
```

### Disable deprecation warning

Pharo contains a deprecation warning system to help the developers to keep their code up to date but in productions those warnings should be removed so that the user will not be bothered by them in case a deprecated method is called.

You can do that via:

```Smalltalk
Deprecation
	raiseWarning: false;
	showWarning: false
```

### Enable the run without sources and changes files

It is possible to run a Pharo image without `.changes` or `.sources` files.

To do that you can execute:

```Smalltalk
NoChangesLog install.
NoPharoFilesOpener install
```

Note that FFI needs the sources to work properly. In Pharo 7 a pluggin to remove this need was introduced.
If your application uses FFI calls you will need to execute:

```Smalltalk
FFICompilerPlugin install
```

### Disable creation of STDio files on Windows

On Windows there is two way to launch a Pharo image. The first uses the `Pharo.exe` executable and the second `PharoConsole.exe`. The difference between those two methods is that the former will be launched without a terminal and will create files to write STDio outputs. The second will open a terminal with Pharo to manage STDio.

It is possible to disable the writing of the STDio files on Windows with this code:

```Smalltalk
Stdio useNullStreams
```

### Remove tests and example packages

In production examples and tests packages are useless. You can find bellow a script to unload them. 

> Be careful, this script is based on a heuristic. If the naming convensions or dependencies are not well managed this might break your application. Please test you application after using such a script.

```Smalltalk
| substrings |
substrings := #('Test' 'Example' 'Mock' 'Demo').

RPackageOrganizer default packages
	select: [ :p | substrings anySatisfy: [ :aString | p name includesSubstring: aString ] ]
	thenDo: #removeFromSystem
```

### Disable Monticello cache

Monticello uses by default a cache when it is used. It is possible to disable this cache with this script:

```Smalltalk
MCCacheRepository uniqueInstance disable
```

### Disable Epicea

Pharo contains a record system to recover changes: *Epicea*. This system log a lot of events on disk.

It is possible to disable Epicea like this:

```Smalltalk
EpMonitor reset
```

### Garbage collect

As last step of the deployment I would recommand the user to launch a full garbage collection of the system to clean all dead instances from the image:

```Smalltalk
5 timesRepeat: [ Smalltalk garbageCollect ]
```

### Delete pharo-local folder

Pharo works with a local folder containing caches. This folder is called `pharo-local` and is next to the image since Pharo 7. It is recommanded to delete this folder, or to not include this folder in the distribution.

## Sources obfuscation

When deploying a commercial application on the customer's infrastructure, we might want to protect our code. This section will give some advice on how to protect the source code of your application.

> WARNING: What will be describe here is not a perfect solution. We are aware it will still have some weakness, but at least it will make it much harder to get the source code of the application.

This section works with the previous section aswell. We recommand to:
* Run without the sources file
* Run without the changes file
* Disable Epicea
* Remove the loggins of your image

### Force omission of startup preferences

At launch Pharo try to load preferences. Since the user can execute Smalltalk code via those preferences, we recommand to disable the preference mechanism with this code:

```Smalltalk
PharoCommandLineHandler forcePreferencesOmission: true
```

### Protect command lines by a password

Since the user can intereact with Pharo via command line, we recommand to protect command lines with a password.

The password is not be saved in clear. It is hashed using pepper and iterations.

If you wish to define *application* command lines who does not need a password protection, implement the method `requireDeploymentPassword` on the class side of your command lines to return `false`.

```Smalltalk
"Enable password protection"
CommandLinePasswordManager protectCommandLinesByPasswordWith: 'PharoPassword'.

"You can also customize the pepper and number of iterations for the hashing of the password."
CommandLinePasswordManager protectCommandLinesByPasswordWith: 'PharoPassword' pepper: 'SomePepper' numberOfHashIterations: 10.

"Remove password protection"
CommandLinePasswordManager removePasswordProtection.
```

### Remove the decompiler

Without the sources and changes files the user does not have the source code shipped with the application, but he still has the byte code of the application. To make it harder to exploit if he succeed to get a part of the byte code, you can unload the decompiler from the image with the piece of code:

```Smalltalk
RPackageOrganizer default packages
	select: [ :p | p name includesSubstring: 'Flashback' ]
	thenDo: #removeFromSystem
```

### Disable global shortcuts

If the customer has access to the Pharo image it is recommanded to disable global shortcuts that can help to open tools. 

It is doable this way:

```Smalltalk
(KMRepository default globalCategories flatCollect: [ :each | each allEntries keymaps ]) do: #disable
```

### Disable WorldMenu, Menubar and Taskbar

To block the access to the tools it is possible to disable the world menu, the taskbar and the menu bar from Pharo with this piece of code:

```Smalltalk
"Disable world menu and menubar"
WorldState desktopMenuPragmaKeyword: ''.

"Disable Menubar only"
MenubarMorph showMenubar: false.

"Disable WorldMenu only"
PasteUpMorph shouldShowWorldMenu: false.

"Disable taskbar"
TaskbarMorph showTaskbar: false.
```

### Disable progress bar interrupt button

If you show progresses in your application via a progress bar, the user can clic on the red cross to stop the action and open a debugger.

It is possible to remove this possibility executing:

```Smalltalk
JobProgressBarMorph isInterruptable: false
```

### Disable process interruption button

In Pharo, it is possible to disable the current process via the `cmd + .` shortcut. This feature can be disabled:

```Smalltalk
UserInterruptHandler cmdDotEnabled: false
```

### Disable drag and drop in Pharo

It is possible to drop files in Pharo to install code in it. It is recommanded to disable this feature to block users to inject code into the application. Since there is no setting to do that, you can recompile a part of the Pharo image to block it this way:

```Smalltalk
WorldMorph allowDropFiles: false
```

### Disable Morph's Halos

To remove the option to open Halos around the Morphs of Pharo you can execute:

```Smalltalk
Morph halosEnabled: false
```

### Disable Debugger

#### Pharo 8

Since Pharo 8, Pharo comes with new debuggers you can choose from.

When deploying a private application you don't want the user to get a bug and access to the code through it. For that you can use the `NoDebugger`:

```Smalltalk
NoDebugger beCurrent
```

#### Pharo < 8 or specific debuggers

In case you are using Pharo < 8 or you want a special handling of the bug you can create your own debugger.

For that you need to create a object and implement a class side method called `#openOn:withFullView:andNotification:`.

For example for a `NoDebugger`:

```Smalltalk
NoDebugger class>>openOn: aDebugSession withFullView: aBool andNotification: aString
	"Do nothing"
```

For a debugger exporting in a file the error:

```Smalltalk
openOn: aDebugSession withFullView: aBool andNotification: aString
	'errors.log'
		ensureCreateFile;
		writeStreamDo: [ :s |
			s
				setToEnd;
				<< 'ERROR. Here is the stack:';
				<< OSPlatform current lineEnding.
			aDebugSession interruptedContext shortDebugStackOn: s ]
```

You then need to register the debugger:

```Smalltalk
Smalltalk tools register: NoDebugger as: #debugger
```

### Open a morph in full screen

When deploying the application, while there is no real headless mode in Pharo or when the application contains a user interface embedded we can open a Morph in full screen to ensure the user cannot access to content behind it. 

To do that we can create a Spec application (in case of headless application it can just contains a logo and a `quit` button) and open it in full screen with this command:

```Smalltalk
MyPresenter new openWorldWithSpec
```

## Change the logo and window title of the application

In Windows it is possible to change the title and the logo of the Pharo application. 

To do that you can execute:

```Smalltalk
DisplayScreen setWindowTitle: 'MyApplication'.

DisplayScreen hostWindowIcon: (FileLocator imageDirectory / 'testLogo.ico') asFileReference fullName.
```

## Deploy a Seaside application

This section will cover a specific kind of deployment: the deployment of a web application with Seaside.

### Prepare the image

It is recommanded to prepare the image for deployment. This section will cover some possible configurations you can apply to your image.

> Note: This is section only contains suggestions and it might be missing interesting options. If you have an idea of missing section do not hesitate to open an issue.

#### Set server mode

When deploying an application as a server, it is possible to change a setting to slow down the rendering cycle of the image and increase performances. It can be done like this:

```Smalltalk
WorldState serverMode: true
```

#### Unregister applications

When building your seaside image it is possible that some Seaside application got registered (demos for examples). 

It is possible to unregister them like this:

```Smalltalk
applicationsToUnregister := WAAdmin defaultDispatcher handlers keys \ #('myApplication' 'files' 'myHandler' 'config').
applicationsToUnregister do: [ :appName | WAAdmin defaultDispatcher unregister: (WAAdmin defaultDispatcher handlerAt: appName) ]
```

#### Set default application

Applications must have a name in Seaside and the name should be in the URL. However, it is possible to define a default application which will be selected in case no application name is in the URL. 

```Smalltalk
WAAdmin defaultDispatcher defaultName: 'myApplicationName'
```

#### Disable development toolbar

In case you load a version of Seaside containing development tools, your application will come with a development toolbar. 

It is possible to remove it by executing:

```Smalltalk
WAAdmin applicationDefaults removeParent: WADevelopmentConfiguration instance ].
```

Then you need to initialize you application. 

#### Protect configuration by a password

In case you keep the configuration application available to the user, you might want to protect it by a password. It wan be done like this:

```Smalltalk
| application |
application := WAAdmin defaultDispatcher handlerAt: 'config'.
application configuration addParent: WAAuthConfiguration instance.
application
	preferenceAt: #login put: 'admin';
	preferenceAt: #passwordHash put: (GRPlatform current secureHashFor: 'seasideiscool').
application addFilter: WAAuthenticationFilter new
```

### Deploy with a Ngnix server

This section will cover the configuration needed to deploy an image with a nginx server.

#### Launch the image

In general I (the author of this decumentation) use a Jenkins to generate my image and then I have a script to deploy the image.

My script looks like this:

```bash
#!/usr/bin/env bash
set -vx

# Where to deploy the application
export DEST=/srv/app/mdl
# Pharo version for the deployment
export PHARO=61
# Location of the zip containing the archive
export ARCHIVE_LOCATION=/var/lib/jenkins/workspace/MaterialDesignLite/PHARO/$PHARO/VERSION/master/

# To launch an image I uses a screen, else the image will close with my ssh session. Here I ensure the session used is closed.
screen -S mdl -X quit

# Remove the old version
rm -rf $DEST/{MaterialDesignLite.*,pharo*,*.sources,Pharo*}

# Copy the application
cp ${ARCHIVE_LOCATION}MaterialDesignLite.zip $DEST/
cd $DEST

# Get a VM and unzip the application
wget --quiet -O - get.pharo.org/vm${PHARO} | bash
unzip MaterialDesignLite.zip

# Launch the application and initialize it on a free and open port
./pharo MaterialDesignLite.image eval --save "
MDLDemo initializeAs: 'mdl'.

WAAdmin defaultDispatcher defaultName: 'mdl'.

ZnZincServerAdaptor startOn: 8088"

#Launch the image in a screen
screen -Sdm mdl ./pharo MaterialDesignLite.image --no-quit
```
#### HTTP deployment

Now that the image is launched we need to dispatch it via nginx.

In order to do that over HTTP I uses this configuration:

```nginx
server {
  listen 80; #Since it's a web application, listen port 80
  listen [::]:80; #Same for IPv6
  server_name {Domaine name. Example mysite.com}; #Set your domaine name
  server_tokens off;  #Do not display nginx version for security reasons

  access_log /var/log/nginx/{log name}.log; #loging
  error_log /var/log/nginx/{error log name}.log; #error loging

  root {Path to the root. For example /srv/myApp/};

  location = / {
    try_files $uri $uri/index.html @proxy;
  }

  #use a proxy for your seaside application
  location @proxy {
    rewrite ^ /{Seaside application name. For example TelescopeDemo}$1 last;
  }

  location /{Seaside application name. For example TelescopeDemo} {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_pass http://127.0.0.1:{Port on which your ZincServerAdaptor listen. For example 8080};
  }

  # This is for the file libraries
  location /files {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_pass http://127.0.0.1:{Port on which your ZincServerAdaptor listen. For example 8080};
  }

}
```
#### HTTPS deployment

The previous option works but is not secured. It is recommanded to generate a TLS certificate (with `let's encrypt` via `certbot` for example) and to deploy over HTTPS.

Then the configuration will look like this:

```nginx
server {
  listen 80; #Since it's a web application, listen port 80
  listen [::]:80; #Same for IPv6
  server_name {Domaine name. Example mysite.com}; #Set your domaine name
  server_tokens off;  #Do not display nginx version for security reasons
  return 301 https://$server_name$request_uri; #Redirect HTTP -> HTTPS
}

server {
  listen 443 ssl http2; #Listen to port 443 for HTTPS
  listen [::]:443 ssl http2; #Same for IPv6
  server_name {Domaine name. Example mysite.com}; #Set your domaine name
  server_tokens off;  #Do not display nginx version for security reasons
  ssl_certificate {path to your public certificate key}.pem;
  ssl_certificate_key {path to your private certificate key}.pem;

  access_log /var/log/nginx/{log name}.log; #loging
  error_log /var/log/nginx/{error log name}.log; #error loging

  root {Path to the root. For example /srv/myApp/};

  location = / {
    try_files $uri $uri/index.html @proxy;
  }

  #use a proxy for your seaside application
  location @proxy {
    rewrite ^ /{Seaside application name. For example TelescopeDemo}$1 last;
  }

  location /{Seaside application name. For example TelescopeDemo} {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_pass http://127.0.0.1:{Port on which your ZincServerAdaptor listen. For example 8080};
  }

  # This is for the file libraries
  location /files {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_pass http://127.0.0.1:{Port on which your ZincServerAdaptor listen. For example 8080};
  }
}
```



================================================
FILE: General/Exceptions.md
================================================
# Exceptions

All applications have to deal with exceptional situations.
Arithmetic errors may occur (such as division by zero), unexpected situations may arise (file not found), or resources may be exhausted (network down, disk full, etc.).
In languages like C, the solution is to have operations that fail return a special error code; this means that client code must check the return value of each operation, and take special action to handle errors. This leads to brittle code.

Modern programming languages, including Pharo, offer a dedicated exception-handling mechanism that greatly simplifies the way in which exceptional situations are signaled and handled.
This mechanism is the **Exception** mechanism.

- [Exceptions](#exceptions)
  * [Basic Uses](#basic-uses)
    + [Signaling an exception](#signaling-an-exception)
    + [Handling exceptions](#handling-exceptions)
    + [Creating your own exceptions](#creating-your-own-exceptions)
    + [Ensure](#ensure)
    + [IfCurtailed](#ifcurtailed)
  * [Advanced Uses](#advanced-uses)
    + [Return](#return)
    + [Retry](#retry)
    + [Resume](#resume)
    + [Pass](#pass)
    + [Outer](#outer)
    + [Resignal](#resignal)
  * [A deeper look at the exception mechanism](#a-deeper-look-at-the-exception-mechanism)
  * [Credits](#credits)

## Basic Uses

### Signalling an exception

**Syntax:**  
`anException signal`  
or:
`anException signal: 'message with additional information'`

Imagine you have a method `potentiallyProblematicMethod`, that sometimes sets a variable to a bad value. When this happens (line 3), you want to signal this problem by **signalling** an exception (in this example an `Error` exception).

```Smalltalk
potentiallyProblematicMethod
	self doThings.
	(myVariable = badValue) ifTrue: [ ^ Error new signal: 'Oh my god no!'].
	^ myVariable.
```

If you execute this code, the following window opens:
![Image](./Exceptions_Image_ExamplePreDebugger.png)

And if you click on "Debug", a debugger opens to help you understand why your application signalled an exception.
![Image](./Exceptions_Image_ExampleDebugger.png)

### Handling exceptions
**Syntax:**  
`protectedBlock on: anExceptionClass do: handlerBlock`.  
Handling multiple exception classes:  
`protectedBlock on: anExceptionClass, anotherExceptionClass, yetAnotherExceptionClass... do: handlerBlock`.  
Accessing the exception in the handler block:  
`protectedBlock on: anExceptionClass do: [:exceptionToHandle| yourCode]`.

As seen in the previous paragraph, if an exception is signalled and nothing else is done, a debugger opens. It is useful when developing, but in the end you probably want your application to catch these exceptions and handle them itself if possible (for example by displaying a nice pop-up informing the user of the problem). This is done with exception **handlers**.

In Pharo, an exception handler is of the form:  
`protectedBlock on: anExceptionClass do: handlerBlock`.  
Here's what happens (in English): *"Evaluate `protectedBlock`. If it signals an exception of the class `anExceptionClass`, catch this exception and evaluate `handlerBlock` instead"*.

To continue the previous example, let's say that `potentiallyProblematicMethod` is called by `solidMethod`. Now `solidMethod` is solid, so it does not want debuggers to open when it is executed. Instead, if an exception is signalled by `potentiallyProblematicMethod`, it will handle it, display a pop-up informing the user, and return `42` instead of the result of `potentiallyProblematicMethod`.

```Smalltalk
solidMethod
	^ [self potentiallyProblematicMethod]
		on: Error
		do: [UIManager default inform: 'There was an issue, but it`s ok'. 42.]
```

Now when `solidMethod` is executed, it either returns the result of `self potentiallyProblematicMethod` if no `Error` is signalled, or it displays a pop-up and returns 42 if an `Error` is signalled.

![Image](./Exceptions_Image_InformationPopUp.png)

When an exception is signalled, it walks the call stack (from the current method to its caller, then the caller of the caller, etc...) until it finds a handler that can handle it. If no handler is found, a debugger is opened.

### Creating your own exceptions
`Error` is not the only kind of exception that can be signalled, there are a lot more! The following picture shows a few examples.


![Image](./Exceptions_Image_ExceptionSample.png)

An issue with writing handlers for generic exception types like `Error` is that these handlers will not only handle errors your application signals (which is fine), but they will also handle errors signalled by the libraries you use, or code that your application uses but that is not a part of it. This is potentially dangerous, as your application may not be doing the right thing for these errors.

To prevent this, you can define your own types of exceptions by creating subclasses of the `Exception` class, and signal and catch these.

To continue the example, we could create an `Exception` subclass named `MyVariableHasABadValue`, and update `potentiallyProblematicMethod` and `solidMethod` as follows:

```Smalltalk
potentiallyProblematicMethod
	self doThings.
	(myVariable = badValue) ifTrue: [ ^ MyVariableHasABadValue new signal: 'Oh my god no!'].
	^ myVariable.
```

```Smalltalk
solidMethod
	^ [self potentiallyProblematicMethod]
		on: MyVariableHasABadValue
		do: [UIManager default inform: 'There was an issue, but it`s ok'. 42.]
```

### Ensure
**Syntax:**  
`aBlock ensure: ensuredBlock`.

The `ensure:` message can be sent to a block to make sure that, even if the block fails (e.g., signals an exception) the argument block will still be executed.  

This is useful to guarantee that `ensuredBlock` will be executed no matter what, for example to close files or clean up in case `aBlock` signals an exception, before the exception is transmitted.

### IfCurtailed
**Syntax:**  
`aBlock ifCurtailed: curtailBlock`

The `ifCurtailed:` message is similar to `ensure:`, but its argument block is evaluated **only** if the receiver block signals an exception.  

## Advanced Uses
After catching an exception in a handler, there are a number of advanced things you can do with the exception.

### Return
**Syntax:**  
`protectedBlock on: anExceptionClass do: [:ex | aValue ]`  
or: `protectedBlock on: anExceptionClass do: [:ex | ex return ]`  
or: `protectedBlock on: anExceptionClass do: [:ex | ex return: aValue ]`  

**Synopsis:**  
This is the standard behavior of handler blocks. If an exception is caught, this handler returns an alternative value for the protected block (the execution continues as if the protected block has returned that value).

Here is a picture of the context stack (a.k.a. call stack) explaining this operation.
![Image](Exceptions_Image_WhatCanYouDoWithAnExceptionYouCaught_fragment1_return.png)

### Retry
**Syntax:**  
`protectedBlock on: anExceptionClass do: [:ex | ex retry ]`  
or: `protectedBlock on: anExceptionClass do: [:ex | ex retryUsing: aBlock ]`  

**Synopsis:**  
Re-execute the protected block (if using `#retry`), or replace the protected block with a different block and then re-execute it (if using `#retryUsing:`).

Here is a picture of the context stack (a.k.a. call stack) explaining this operation.
![Image](Exceptions_Image_WhatCanYouDoWithAnExceptionYouCaught_fragment2_retry.png)

### Resume
**Syntax:**  
`protectedBlock on: anExceptionClass do: [:ex | ex resume ]`  
or: `protectedBlock on: anExceptionClass do: [:ex | ex resume: aValue ]` 

**Synopsis:**  
Resume the execution of the protected block just after the call to #signal. The call to #signal is worth `nil` (if using `#resume`) or `aValue` (if using `#resume: aValue`).


Here is a picture of the context stack (a.k.a. call stack) explaining this operation.
![Image](Exceptions_Image_WhatCanYouDoWithAnExceptionYouCaught_fragment3_resume.png)

### Pass
**Syntax:**  
`protectedBlock on: anExceptionClass do: [:ex | ex pass ]`  

**Synopsis:**  
Skip the current handler and keep looking for another handler to handle this exception.



### Outer
**Syntax:**  
`protectedBlock on: anExceptionClass do: [:ex | ex outer ]`  

**Synopsis:**  
Like `ex pass`, but if another handler later calls `#resume` on the exception, the execution resumes where `#outer` was called instead of where the exception was signalled.  
If multiple `#outer` are executed on the same exception, they will form a sort of stack of positions to go back to, in case `#resume` is called multiple times on the exception.

Here is a picture of the context stack (a.k.a. call stack) explaining this operation.
![Image](Exceptions_Image_WhatCanYouDoWithAnExceptionYouCaught_fragment4_outer.png)

### Resignal
**Syntax:**  
`protectedBlock on: anExceptionClass do: [:ex | ex resignalAs: anotherException ]`  

**Synopsis:**  
Signals `anotherException` as if it had been signalled at the same place the original exception (`ex`) was signalled.  
This can be used to catch generic exceptions and re-signal them as application-specific exceptions if they meet some criteria.

## A deeper look at the exception mechanism

The following image gives a graphical view of what happens when an exception is signalled, and the different situations that can arise.
![Image](Exceptions_Image_WhatHappensWhenAnExceptionIsSignalled.png)

## Credits
Parts of this page are based on the **Handling Exceptions** chapter of the [Deep Into Pharo book](http://files.pharo.org/books-pdfs/deep-into-pharo/2013-DeepIntoPharo-EN.pdf).  
Pictures by Thomas Dupriez.


================================================
FILE: General/ExportFormats.md
================================================
# Source Code Export formats

Pharo stores its source code in memory (by default) or in a snapshot of the memory when we save a Pharo image. This makes it complicated to manage source code in the long term or to collaborate with others.

In order to be able to save some source code in readable files, Pharo includes some textual export formats. This page will explain the main export formats used to save code in VCS such as git.

This page will present formats from the most recommended for new projects to the less recommended.

- [Comparisons](#comparisons)
  * [Overview](#overview)
  * [Supported Pharo versions](#supported-pharo-versions)
- [Tonel](#tonel)
  * [Tonel Pros and Cons](#tonel-pros-and-cons)
  * [Tonel supported Pharo versions](#tonel-supported-pharo-versions)
  * [Tonel versions](#tonel-versions)
- [FileTree metadata less](#filetree-metadata-less)
  * [FileTree metadata less Pros and Cons](#filetree-metadata-less-pros-and-cons)
  * [FileTree metadata less supported Pharo versions](#filetree-metadata-less-supported-pharo-versions)
- [FileTree metadata full](#filetree-metadata-full)
  * [FileTree metadata full Pros and Cons](#filetree-metadata-full-pros-and-cons)
  * [FileTree metadata full supported Pharo versions](#filetree-metadata-full-supported-pharo-versions)


## Comparisons

### Overview 

|| Tonel | FileTree metadata less | FileTree metadata full |
| ------------- | ------------- |------------- |------------- |
| Work out of the box since Pharo | 6.1 | 4 | 3 |
| Older version supported after update | 4 | 4 | 3 |
| Export granularity | Class | Method | Method |
| Works well on windows | :white_check_mark: | :x: | :x: |
| Easy to merge two branches | :white_check_mark: | :white_check_mark: | :x: |
| Takes a reasonable space on file system | :white_check_mark: | :x: | :x: |
| Works with Iceberg | :white_check_mark: | :white_check_mark: | :x: |
| Works with Monticello | :white_check_mark: | :white_check_mark: | :white_check_mark: |

### Supported Pharo versions

| Pharo Version | FileTree metadata full | FileTree metadata less | Tonel |
| ------------- | ------------- |------------- |------------- |
3 |  :white_check_mark: | :x: | :x: |
4 |  :white_check_mark: |  :white_check_mark: | Update Metacello + Install Tonel |
5 |  :white_check_mark: |  :white_check_mark: | Update Metacello + Install Tonel |
6.0 |  :white_check_mark: |  :white_check_mark: | Update Metacello + Install Tonel |
6.1 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
7 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
8 | :white_check_mark: | :white_check_mark: | :white_check_mark: |

## Tonel 

Tonel ([https://github.com/pharo-vcs/tonel](https://github.com/pharo-vcs/tonel)) is an export format introduced in Pharo 6.1. 

It creates one file by class or extended class and works well on Windows (compared to file tree).

### Tonel Pros and Cons

Pros
- Works well on Windows 
- Not much space lost because of small files
- Export readable files
- No problem during merge because of metadata

Cons
- Works out of the box since Pharo 6.1.
- Since the format is more recent than the others, some edges cases might cause trouble. (It rarely happens)

### Tonel supported Pharo versions

Tonel works out of the box in Pharo 6.1 and higher. But it is possible to make it work in Pharo 4 to 6.0 by updating Metacello and installing Tonel.

```Smalltalk
Metacello new
	baseline: 'Metacello';
	repository: 'github://Metacello/metacello:pharo-6.1_dev/repository';
	get.
Metacello new
	baseline: 'Metacello';
	repository: 'github://Metacello/metacello:pharo-6.1_dev/repository';
	onConflict: [:ex | ex allow];
	load.
Metacello new 
	repository: 'github://pharo-vcs/tonel';
	baseline: 'Tonel';
	load.
```

### Tonel versions

Tonel got multiple versions over the years, each tweaking the export format:
- version 1.0: original tonel export format
- version 2.0: this version ensure that in the metadatas the keys are symbols and the values are strings. This change happened in order to be compatible with Gemstone. Note that this format was never used as a default export format of Pharo
- version 3.0: this version has the changes of the 2.0 but it also adds the properties `package` and `tag` to replace the `category` property for class definitions. This is to remove same ambiguity in the class definitions. The `category` property is kept by default for backward compatibility, but the TonelWriter can be configured to not export this property. This format can also be improved to export more metadata. For example, it is planned to export a property `deprecatedAliases` to manage some class deprecations in the future.

If you want to change your export format and convert all the files of a repository at once to avoid to have multiple PR with format changes you can use the following script.
Take a Pharo 12 or Pharo 13 images and run the following script. It will convert all the loaded packages in your image so you may load extra packages to prepare such operation. 

```st
| projectName repository |
projectName := 'ProjectNameInIceberg'.
repository := IceRepository repositories detect: [ :repo | repo name = projectName ].
repository workingCopy packages do: [ :pkg |
IceLibgitTonelWriter forInternalStoreFileOut: pkg latestVersion mcVersion on: repository ]
```

**NOTE: you must ensure all your project packages are loaded in the image (check in the Repository | Packages window, and right click load any that aren't).**

Once you have run this script, use the "Repository, Project | Extra | Open in native file browser" menu option to open an OS terminal and then run:
```
git commit -a -m "Update tonel formal to V3"
git push
```

Since Pharo 12, it is also possible to indicate in a Tonel project which version of Tonel to use to export some code. The file to update is the `.properties` file that is in the source folder and it should look like this:

```
{
    #format : #tonel,
    #version: #'1.0' //could be 2.0 or 3.0
}
```

This is useful for example if a project has contributors on P11 using v1 format and contributors in P12 using v3 format since P11 is unable to export Tonel v3 format. 

## FileTree metadata less 

FileTree ([https://github.com/dalehenrich/filetree](https://github.com/dalehenrich/filetree)) is the first export format that was integrated in the goal to use Pharo with Git. The first version had a lot of metadata (see section Filetree metadata full), the second was a new version with metadata less format. 

This format exports one file per method. This can cause trouble with Windows because Windows has a maximum path and file name length of 255 characters. This limit can easily be reached with FileTree. 

Another problem of the FileTree format is that most Pharo's methods are short and creating one file by method waste a lot of space because the physical representation of files on a drive has a minimal size (4 KiB on NTFS file systems) that is reached by most of Pharo's method. 

Its advantage compared to FileTree metadata full is that there is no problem during the merge of the source code thanks to the absence of metadata.

### FileTree metadata less Pros and Cons 

Pros
- Easy to browse the history of a method
- Present since Pharo 4 out of the box
- No problem during merge because of metadata

Cons
- Cause trouble on Windows
- Waste space on the file system

### FileTree metadata less supported Pharo versions

FileTree metadata less is supported out of the box since Pharo 4.0 and cannot easily be used in older Pharo versions. 

## FileTree metadata full

FileTree metadata full ([https://github.com/dalehenrich/filetree](https://github.com/dalehenrich/filetree) )is the ancestor of FileTree metadata less and works in the same way but also export a lot of metadata relating to the commits such has a commit message (different from the one of the VCS), the timestamp of the method compilation, etc.

This simplifies the tooling because the tools can get some information from the metadata instead of the VCS but it also creates a lot of trouble while merging two branches using this format.

Merges can be eased via this project: [https://github.com/ThierryGoubier/GitFileTree-MergeDriver](https://github.com/ThierryGoubier/GitFileTree-MergeDriver)

This format can be used via Monticello but not via Iceberg. Iceberg will ignore the format and export in FileTree metadata less.

### FileTree metadata full Pros and Cons

Pros
- Easy to browse the history of a method
- Present in most Pharo versions out of the box

Cons
- Cause trouble on Windows
- Waste space on the file system
- Hard to merge two branches because of metadata
- Does not work with Iceberg, the default git tool since Pharo 7

### FileTree metadata full supported Pharo versions

This format works out of the box in most Pharo versions.


================================================
FILE: General/Extensions.md
================================================
# Extensions

- [Extensions](#extensions)
  - [Use of Extension methods](#use-of-extension-methods)
  - [Add a new extension method](#add-a-new-extension-method)
    - [Define an extension method in versions prior to Pharo 7](#define-an-extension-method-in-versions-prior-to-pharo-7)
    - [Define an extension method since Pharo 7](#define-an-extension-method-since-pharo-7)
    - [Define an extension method programmatically](#define-an-extension-method-programmatically)
  - [Find methods currently extending a class](#find-methods-currently-extending-a-class)
    - [In versions prior to Pharo 7](#in-versions-prior-to-pharo-7)
    - [Since Pharo 7](#since-pharo-7)
    - [Find extensions programmatically](#find-extensions-programmatically)
  - [Package loading order is important](#package-loading-order-is-important)

Pharo includes a system of extension methods. This feature allows the developer to add behavior (but not state) to existing objects in Pharo. 

> Note that it is only possible to add methods (behavior) as extension and not variables (state)

There is no syntactic difference between calling an extension method and calling a method declared in the class. The main difference between methods and extension methods is that extension methods are stored in a different package than the class they are implemented on.

## Use of Extension methods

Extension methods are useful when we want to use some behavior on an object, but it does not make sense to package it directly with the object. For example we might want to ask to a model object for information related to its display in a GUI, but to keep layers as cohesive as possible, we do not want display information stored in the code package of our application. In this case, we can add those methods to the model object but package those methods in a GUI package.

Another case might be when you want to enhance the behavior of a package that is simply not your own. You could add the methods to the class in the different package, but committing those changes to source control is not practical (i.e., you don't want to make a branch of the package, and doing a pull request would take a long time, etc.). With extension methods, the changes you make to the foreign package are stored in your own package, so they belong to you. 

## Add a new extension method

Internally, an extension method is a method whose protocol has a pattern `*MyPackageExtendingMyClass`. 

Here is more detailed information about adding an extension method via Pharo's tooling.

### Define an extension method in versions prior to Pharo 7

In the Pharo versions based on Nautilus system browser, extension methods are created when we categorize methods on a protocol beginning by a `*`.

![Add an extension method via Nautilus 1](Extensions_Image_NautilusAddExtension1.png?raw=true "Add an extension method via Nautilus 1")

![Add an extension method via Nautilus 2](Extensions_Image_NautilusAddExtension2.png?raw=true "Add an extension method via Nautilus 2")

### Define an extension method since Pharo 7

Since Pharo 7 the default system browser is Calypso. To add an extension method in Calypso you need to use the "Move to package" menu entry.

![Add an extension method via Calypso](Extensions_Image_CalypsoAddExtension.png?raw=true "Add an extension method via Calypso")

If you already have extensions in this package, you can also select the package in the list of extending packages in the protocol pane before adding a method.

### Define an extension method programmatically

```Smalltalk
ExistingClass compile: 'myMethod
	^ true' classified: '*MyPackage'
```

## Find methods currently extending a class

There are two ways to find which methods are extensions where they are located:

- Browse a class and check the protocols pane. (See examples below)

- Look at a package and check the bottom of the class pane. The last classes will appear in grey and will be the classes extended in that package.

### In versions prior to Pharo 7

![See an extension method via Nautilus](Extensions_Image_NautilusSeeExtensions.png?raw=true "See an extension method via Nautilus")

### Since Pharo 7

![See an extension method via Calypso](Extensions_Image_CalypsoSeeExtensions.png?raw=true "See an extension method via Calypso")

### Find extensions programmatically

To find extension methods programmatically you can do something like:

```Smalltalk
(Number methods select: #isExtension) groupedBy: #package
```

> **TODO: Add example of refactoring to an extension?**


## Package loading order is important

One thing developers should take into account when using extensions is to have clean dependencies between its packages. A package extending classes from another package should be loaded *after* this package.

For example, if my package `MyProject-GUI` extends `MyProject-Model`, `MyProject-Model` should always be loaded *before* `MyProject-GUI` is. For more details, see the dependencies sections in the [baseline guide](Baselines.md).


================================================
FILE: General/Files.md
================================================
# Files
TODO: explain how to manipulate files, paths, file systems, etc...


================================================
FILE: General/GithubActions.md
================================================
# Setting up your continuous integration via GitHub Actions

Previously, the Pharo community was heavily relying on Travis CI for the continuous integration of projects hosted on GitHub.
But Travis becoming pay-to-use service, the community created some tooling to manage the CI via GitHub Actions. 

This guide will get you through the process to set up your own integration.

> Note: In order to do anything for the CI of your project, you will need a `Baseline` to manage its dependencies. If it is not the case yet, you can check the [guide on baselines](Baselines.md).

- [Setting up your continuous integration via Github Actions](#setting-up-your-continuous-integration-via-github-actions)
  * [Simple case: Run tests on master branch](#simple-case-run-tests-on-the-master-branch)
  * [SmalltalkCI options](#smalltalkci-options)
    + [Load spec options](#load-spec-options)
    + [Testing options](#testing-options)
    + [Code Coverage](#code-coverage)
    + [Using custom scripts](#using-custom-scripts)
  * [Testing multiple versions of Pharo at once](#testing-multiple-versions-of-pharo-at-once)
  * [Testing on multiple OS](#testing-on-multiple-os)
  * [Manage the workflow target (branchs, PR, ...)](#manage-the-workflow-target-branchs-pr-)
    + [Target branches](#target-branches)
    + [Target pull requests](#target-pull-requests)
    + [Target releases](#target-releases)
    + [Target scheduled workflow](#target-scheduled-workflow)
    + [Other targets](#other-targets)
  * [Managing multiple workflows and SmalltalkCI configurations](#managing-multiple-workflows-and-smalltalkci-configurations)
  * [Continuous releases](#continuous-releases)
  * [Save releases artifacts](#save-releases-artifacts)
  * [Depending on resources of your repository with GitBridge](#depending-on-the-resources-of-your-repository-with-gitbridge)
  * [Add your build artifacts to PharoLauncher](#add-your-build-artifacts-to-pharolauncher)
  * [External ressources](#external-ressources)

## Simple case: Run tests on the master branch

Let's start simple! This section will explain how to set up a workflow to launch the tests of the project on every commit done on the master branch.

To load our Pharo project in the CI and execute the tests, we'll use [SmalltalkCI](https://github.com/hpi-swa/smalltalkCI).
This project needs a configuration file to fetch information on your project. This file should be at the root of your project under the name of `.smalltalk.ston`. 

Here is the most simple configuration:

```ston
SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'MyProject',
      #directory : 'src'
    }
  ]
}
```

This configuration tells smalltalkCI two things:
- The baseline to use to load the project is BaselineOf`MyProject`
- The sources of the project are in /src

Now that smalltalkCI configuration file is created, we just need to define your GitHub workflow file.
This file should be located in `.github/workflows/` folder. Let's call ours `testing.yml`.

```yml
name: CI

on:
  push:
    branches:
      - 'master'

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-image: Pharo64-10
      - run: smalltalkci -s ${{ matrix.smalltalk }}
        shell: bash
        timeout-minutes: 15
```

Let's see a little about what is happening here. 

The #name parameter allows one to give a name to the workflow. This is useful because you might have more than one workflow for your project. 
For example:

![Example of different workflows](GitHubActions_workflows.png)

In this image, we can see a CI that has 3 different workflows:
- CI
- continuous
- Release

Then we have:  

```yml
on:
  push:
    branches:
      - 'master'
```

This is used to define when the workflow should enter into action. In our case, we want it when we `push` on `master` branch.

Then we have:

```yml
    runs-on: ubuntu-latest
```

With this, the workflow will run in the latest version of Ubuntu.


```yml
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

This step adds en environment variable needed by smalltalkCI.

Last but not least, we have the actions to execute:

```yml
    steps:
      - uses: actions/checkout@v3
```

Using the "checkout" action to checkout the project on the CI worker.  

```yml
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-image: Pharo64-10
```

Using the "setup-SmalltalkCI" action to prepare the setup.

```yml
      - run: smalltalkci -s ${{ matrix.smalltalk }}
        shell: bash
        timeout-minutes: 15
```

Loads the project and executes the tests of the project with a 15min timeout.  

This timeout can be increased in case your project tests are longer.  

Once you commit these two files, your project will have a working CI !  
Each time you commit to master, a new build should happen.  
You will be able to see the resulting build in the `Actions` tab in your project.

## SmalltalkCI options

We have seen in the previous section that [SmalltalkCI](https://github.com/hpi-swa/smalltalkCI) relies on a configuration file. 
We did a simple one to start, but there are more options available. We will cover them in this section.  
The full and up-to-date list is available in the [SmalltalkCI's README file](https://github.com/hpi-swa/smalltalkCI/blob/master/README.md).

### Load spec options

In the previous example, we declared a loading spec with a baseline and a code directory. But it is also possible to add more options:

```ston
SCIMetacelloLoadSpec {
  #baseline : 'MyProject',                            // Define MC Baseline
  #directory : 'src',                                 // Path to packages, if packages are on root do not use #directory : '', just don't add this option
  #failOn : [ #OCUndeclaredVariableWarning ],         // Fail build on provided list of Warnings
  #ignoreImage : true,                                // If true, Metacello will force a load of a package, overriding a previously existing one
  #load : [ 'default' ],                              // Define some specific groups to load
  #onConflict : #useIncoming,                         // When there is a conflict between loaded sources and incoming sources (can be #useIncoming|#useLoaded)
  #onUpgrade : #useIncoming,                          // When loaded sources are an older version than incoming sources (can be #useIncoming|#useLoaded)
  #onWarningLog : true,                               // Log Warning messages to Transcript
  #platforms : [ #squeak, #pharo, #gemstone ],        // Define compatible platforms
  #usernameEnvVar : 'GITHUB_USER',                    // Environment variable containing the username used for authentication
  #passwordEnvVar : 'GITHUB_TOKEN',                   // Environment variable containing the password used for authentication
  #registerInIceberg : true                           // Pharo Only | Register the tested repository in Iceberg (false by default)
}
```
### Testing options
It is also possible to customize the testing of the project:

```ston
SmalltalkCISpec {
  ...
  #testing : {
    // Include specific TestCases
    #include : {
      #classes : [ #AnotherProjectTestCase ],
      #categories : [ 'AnotherProject-Tests' ],
      #packages : [ 'AnotherProject.*' ],
      #projects : [ 'BaselineOfMyProject' ]
    },

    // Exclude specific TestCases from testing
    #exclude : {
      #classes : [ #AnotherProjectTestCase ],
      #categories : [ 'AnotherProject-Tests' ],
      #packages : [ 'AnotherProject.*' ],
      #projects : [ 'ConfigurationOfMyOtherProject' ]
    },

    #allTestCases : true, // Run all TestCases in image

    // Define TestCases explicitly
    #classes : [ #MyProjectTestCase ],
    #categories : [ 'MyProject-*' ],
    #packages : [ 'MyProject.*' ],
    #projects : [ 'BaselineOfMyProject' ],

    // Other options
    #defaultTimeout : 30, // In seconds (Squeak, and Pharo 6 or later)
    #failOnSCIDeprecationWarnings : false, // Fail if a deprecated smalltalkCI API is used
    #failOnZeroTests : false, // Pass builds that did not run any tests
    #hidePassingTests : true, // Hide passing tests when printing to stdout
    #serializeError: false // (default: true) Disable serialization of failing test case (e.g. with Fuel in Pharo)
  }
}
```

### Code Coverage

It is possible to see the coverage of our project via SmalltalkCI with [Coveralls](https://coveralls.io/).

To enable this, you need to add a "coverage" section in your configuration:

```ston
SmalltalkCISpec {
  ...
  #testing : {
    ...
    #coverage : {
      #packages : [ 'SomePackage', 'SomePack*' ],
      #classes : [ #ClassToCover ],
      #categories : [ 'SomeClassCategory', 'SomeClassCat*' ],
      #format : #coveralls
    }
  }
}
```

For example our project could look like:

```ston
SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'Myproject',
      #directory : 'src'
    }
  ],
  #testing : {
    #coverage : {
      #packages : [ 'MyProject-*' ]
    }
  }
}
```

This configuration will execute all the tests loaded by the `BaselineOfMyProject` and build the coverage of all packages starting by `MyProject-` for [Coveralls](https://coveralls.io/).
If you enabled your repository in coveralls ([https://coveralls.io/repos/new](https://coveralls.io/repos/new)), the results would be uploaded automatically.

![Coveralls screenshot](GithubActions_coveralls.png)

For more information, check: [SmalltalkCI guide on coverage](https://github.com/hpi-swa/smalltalkCI/blob/master/docs/COVERAGE.md).

### Using custom scripts

SmalltalkCI offers some hooks to be able to run some Pharo scripts at different moments of the project loading and testing.
Four hooks are available:
- `preLoading` : Executed before loading the project
- `postLoading` : Executed after loading the project
- `preTesting` : Executed before testing the project
- `postTesting` : Executed after testing the project

Those parameters can take 3 different parameters. 

The first one is a single script:

```ston
SmalltalkCISpec {
  #preLoading : 'scripts/preLoading.st',
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'Myproject',
      #directory : 'src'
    }
  ]
}
```

The second one is a collection of scripts:

```ston
SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'Myproject',
      #directory : 'src'
    }
  ],
  #postLoading : [
    'scripts/postLoading1.st',
    'scripts/postLoading2.st'
  ]
}
```

And the third one is an instance of SCICustomScript that allows running script only on certain platforms:

```ston
SmalltalkCISpec {
  #preLoading : 'scripts/preLoading.st',
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'Myproject',
      #directory : 'src'
    }
  ],
  #postLoading : [
    SCICustomScript {
      #path : 'scripts/postLoadingSqueak.st',
      #platforms : [ #squeak ]
    },
    SCICustomScript {
      #path : 'scripts/postLoadingPharo.st',
      #platforms : [ #pharo ]
    }
  ]
}
```

Here is a full example:

```ston
SmalltalkCISpec {
  #preLoading : 'scripts/preLoading.st',
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'Myproject',
      #directory : 'src'
    }
  ],
  #postLoading : [
    'scripts/postLoading1.st',
    'scripts/postLoading2.st'
  ],
  #preTesting : SCICustomScript {
    #path : 'scripts/preTesting.st',
    #platforms : [ #squeak, #pharo, #gemstone ]
  },
  #testing : ...,
  #postTesting : [
    SCICustomScript {
      #path : 'scripts/postTestingSqueak.st',
      #platforms : [ #squeak ]
    },
    SCICustomScript {
      #path : 'scripts/postTestingPharo.st',
      #platforms : [ #pharo ]
    }
  ]
}
```

For more informations on SmalltalkCI in general check: [SmalltalkCI documentation](https://github.com/hpi-swa/smalltalkCI).

## Testing multiple versions of Pharo at once

It is rare to have a project working only on one version of Pharo. Thus, it is often useful to have our workflows run on multiple versions. 

This can be achieved this way:

```yml
name: CI

on:
  push:
    branches:
      - 'master'

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    strategy:
      matrix:
        smalltalk: [ Pharo64-9.0, Pharo64-10, Pharo64-11 ]
    name: ${{ matrix.smalltalk }}
    steps:
      - uses: actions/checkout@v3
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-image: ${{ matrix.smalltalk }}
      - run: smalltalkci -s ${{ matrix.smalltalk }}
        shell: bash
        timeout-minutes: 15
```

Here we declared a matrix with multiple versions of Pharo as axes:

```yml
    strategy:
      matrix:
        smalltalk: [ Pharo64-9.0, Pharo64-10, Pharo64-11 ]
```

Each axe will use the name of the Pharo version as name:

```yml
    name: ${{ matrix.smalltalk }}
```

But this could also be another name, such as:

```yml
    name: MyProject-${{ matrix.smalltalk }}
```

Then the builds would be: `MyProject-Pharo64-9.0`, `MyProject-Pharo64-10` and `MyProject-Pharo64-11`.

The names will then be used to display the different builds on Github:

![Screenshot of matrix](GithubActions_matrix.png)

The list of possible Pharo versions are:

| 64bits           | 32bits           |
| ---------------- | ---------------- |
| `Pharo64-alpha`  | `Pharo32-alpha`  |
| `Pharo64-stable` | `Pharo32-stable` |
| `Pharo64-11`     | `Pharo32-11`     |
| `Pharo64-10`     | `Pharo32-10`     |
| `Pharo64-9.0`    | `Pharo32-9.0`    |
| `Pharo64-8.0`    | `Pharo32-8.0`    |
| `Pharo64-7.0`    | `Pharo32-7.0`    |
| `Pharo64-6.1`    | `Pharo32-6.1`    |
| `Pharo64-6.0`    | `Pharo32-6.0`    |
|                  | `Pharo32-5.0`    |
|                  | `Pharo32-4.0`    |
|                  | `Pharo32-3.0`    |

> Note: This list is from February 2023. More versions will be added in the future

## Testing on multiple OS

Usually, our Pharo projects are not influenced by the OS on which it runs. But in some cases, it can be important to test on multiple OS.

This can be achieved this way: 

```yml
name: CI

on:
  push:
    branches:
      - 'master'

jobs:
  build:
    strategy:
      matrix:
        os: [ macos-latest, windows-latest, ubuntu-latest]
        smalltalk: [ Pharo64-9.0, Pharo64-10]
    runs-on: ${{ matrix.os }}
    name: ${{ matrix.smalltalk }} on ${{ matrix.os }}
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-image: ${{ matrix.smalltalk }}
      - run: smalltalkci -s ${{ matrix.smalltalk }}
        shell: bash
        timeout-minutes: 15
```

As we can see here:

```yml
        os: [ macos-latest, windows-latest, ubuntu-latest]
    runs-on: ${{ matrix.os }}
```

We declare that our project will be run on the latest macos, windows and ubuntu to covers the 3 major OS. 

To distinguish the builds, we use the Pharo version and the OS name to name our builds:

```yml
    name: ${{ matrix.smalltalk }} on ${{ matrix.os }}
```

![Screenshot of ci matrix](GithubActions_os.png)

You can find more information on the available OS here: [https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners)

## Manage the workflow target (branchs, PR, ...)

In our simple example at the beginning, we were launching the CI on the master branch, but you will often need to execute the CI on multiple branches.

### Target branches

It is possible to target multiple branches at once. For example:

```yml
on:
  push:
    branches:
      - 'master'
      - 'development'
      - 'feature/**
```

This will launch your workflow for every commit on `master`, `development` or any branch starting with `feature/`. 

You can also target all branches in two ways. The first is by not specifying any:  

```yml
on: [ push ]
```

The second is to use `'**'`:

```yml
on:
  push:
    branches:
      - '**'
```

This second way of declaring "all branches" is useful when you want to execute your workflow on all branches except some of them.
In that case, you can use:

```yml
on:
  push:
    branches:
      - '**'
      - '!doc/**'
```

This template will launch the CI for every commit on any branch except the ones starting with `doc/`.

### Target pull requests

It is also possible to target others kinds of events.
Particularly pull requests made to your project:

```yml
on: [ push, pull_request ]
```

And be even more precise on the kinds of PR that should execute a workflow:  
```yml
on:
  pull_request:
    types: [assigned, opened, synchronize, reopened]
```


Note that this can be done by addition of other targets:

```yml
on:
  push:
    branches:
      - '**'
      - '!master'
  pull_request:
    types: [assigned, opened, synchronize, reopened]
```

Here the workflow runs on every pull request and every commit of any branch except `master`.

### Target releases

It is also sometimes useful to have a workflow targeting releases. We'll exploit that later in this documentation.
In that case you can use:

```yml
on:
  release:
    types: [created, edited]
```

### Target scheduled workflow

In some cases, it might be useful to target the workflow at specific times. 
For example, it happens that some projects are "meta project". Their goal is to load a bunch of other projects. In that case, it's rare that a commit is made direcly in them.
But we want to run the CI on a regular basis to be sure our project still works. In that case, we can use a cron to schedule the workflow:

```yml
on:
  push:
    branches:
      - 'master'
  schedule:
    - cron:  '0 0 * * *'
```

Some utils will help you to configure the parameter of this target such as [Crontab.guru](https://crontab.guru/).

### Other targets

GitHub actions have way more options than the options presented here. The most useful ones were presented here, but you can find more information in [Github documentation](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on)

## Managing multiple workflows and SmalltalkCI configurations

Until now, we managed only one workflow file, but it is possible to manage multiple of them.

To demonstrate this, let's imagine that our project has two groups in its configuration.
The first group loads the core of the project and is the default group of our baseline. 
A second group loads the full projects with additional features. 

We would now like to have two workflows:
- A first workflow launched on all branches and PR to test the core in Pharo 9, 10 and 11
- A second workflow launched on master branch and PR to test the full project in Pharo 11

The first step is to get two smalltalkCI configurations.

A first one will be the default `.smalltalk.ston`.

```ston
SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'MyProject',
      #directory : 'src'
    }
  ]
}
```

And a second one loads the group `all` and is named `.smalltalkFull.ston`.

```ston
SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'MyProject',
      #directory : 'src',
      #load : [ 'all' ]
    }
  ]
}
```

Now that we have our two configurations, we can create our two workflow files. 

The first one is close to what we have seen until here in this documentation:

```yml
name: CI Core

on: [ push, pull_request ]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        smalltalk: [ Pharo64-9.0, Pharo64-10, Pharo64-11 ]
    name: ${{ matrix.smalltalk }}
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-image: ${{ matrix.smalltalk }}
      - run: smalltalkci -s ${{ matrix.smalltalk }}
        shell: bash
        timeout-minutes: 15
```

In the second, we change the targets, and we give one more parameter to the smalltalkCI launch command to specify the path to our specific Smalltalk configuration.

```yml
name: CI Full

on:
  push:
    branches:
      - 'master'
  pull_request:
    types: [assigned, opened, synchronize, reopened]

jobs:
  build:
    runs-on: ubuntu-latest
    name: ${{ matrix.smalltalk }}
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-image: Pharo64-11
      - run: smalltalkci -s ${{ matrix.smalltalk }} .smalltalkFull.ston
        shell: bash
        timeout-minutes: 15
```

Each file uses a different configuration file.
The first workflow file is named `CI` uses the default file `smalltalk.ston` implicitly.
The second workflow file is named `CI full` uses `smalltalkFull.ston` explicitly.


```yml
      - run: smalltalkci -s ${{ matrix.smalltalk }} .smalltalkFull.ston
        shell: bash
        timeout-minutes: 15
```

> Note: If we wanted to run on the same targets with two smalltalkCI configurations, we could also have used another matrix axis and avoid needing of different workflows.

Example:

```yml
name: CI

on: [ push, pull_request ]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    strategy:
      matrix:
        smalltalk: [ Pharo64-9.0, Pharo64-10, Pharo64-11 ]
        config: [ .smalltalk.ston, .smalltalkFull.ston ]
    name: ${{ matrix.smalltalk }} - ${{ matrix.config }}
    steps:
      - uses: actions/checkout@v3
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-image: ${{ matrix.smalltalk }}
      - run: smalltalkci -s ${{ matrix.smalltalk }} ${{ matrix.config }}
        shell: bash
        timeout-minutes: 15
```

Having multiple workflows can have other usages that we explore in the next sections.

## Continuous releases

Until now, we have used Github actions to test our project.  
But Github Actions has more features.  
For instance, we are able to realease our projects.  

In this section, we see how to save the result of the builds of our master branch in a github release.

To do that, we can first remove the master branch from the targets of our test workflow because we will handle the master branch in another workflow.

```yml
on:
  push:
    branches:
      - '**'
      - '!master'
  pull_request:
    types: [assigned, opened, synchronize, reopened]
```

Then we will create another workflow called `.github/workflows/continuous.yml`.

```yml
name: continuous

on:
  push:
    branches:
      - 'master'

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      PROJECT_NAME: MyProject-${{ matrix.smalltalk }}
    strategy:
      matrix:
        smalltalk: [ Pharo64-10, Pharo64-11 ]
    name: ${{ matrix.smalltalk }}
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-version: ${{ matrix.smalltalk }}
      - run: smalltalkci -s ${{ matrix.smalltalk }}
        shell: bash
        timeout-minutes: 15
        
      # Here we zip the result of the build to be able to keep the artefacts
      - name: package
        run: |
          mv /home/runner/.smalltalkCI/_builds/* .
          mv TravisCI.image $PROJECT_NAME.image
          mv TravisCI.changes $PROJECT_NAME.changes
          echo ${${{ matrix.smalltalk }}} | sed -e 's/.*\-//g ; s/\..*//g ; s/$/0/' > pharo.version
          zip -r $PROJECT_NAME.zip $PROJECT_NAME.image $PROJECT_NAME.changes *.sources pharo.version
          ls
        
      #Save the artefact of the build under "continuous" tag
      - name: Update release
        uses: johnwbyrd/update-release@v1.0.0
        with:
          release: 'continuous'
          token: ${{ secrets.GITHUB_TOKEN }}
          files: ${{ env.PROJECT_NAME }}.zip
```

This workflow starts to like what we have seen until now. It checkout our project, install smalltalkCI and runs it. 
But it also adds three steps to the process. 

The first step is to give a name to our project. We will use that name to name our build artifact:

```yml
    env:
      PROJECT_NAME: MyProject-${{ matrix.smalltalk }}
```

In the second step, we rename the image produced by SmalltalkCI. We generate a version file that is useful in tools such as the `PharoLauncher`. And we zip the files in the archive to save.

```yml
      # Here we zip the result of the build to be able to keep the artefacts
      - name: package
        run: |
          mv /home/runner/.smalltalkCI/_builds/* .
          mv TravisCI.image $PROJECT_NAME.image
          mv TravisCI.changes $PROJECT_NAME.changes
          echo ${${{ matrix.smalltalk }}} | sed -e 's/.*\-//g ; s/\..*//g ; s/$/0/' > pharo.version
          zip -r $PROJECT_NAME.zip $PROJECT_NAME.image $PROJECT_NAME.changes *.sources pharo.version
          ls
```

The last step is to publish the artifact in the continuous tag. For that we are using the action `johnwbyrd/update-release@v1.0.0`.

```yml
      #Save the artefact of the build under "continuous" tag
      - name: Update release
        uses: johnwbyrd/update-release@v1.0.0
        with:
          release: 'continuous'
          token: ${{ secrets.GITHUB_TOKEN }}
          files: ${{ env.PROJECT_NAME }}.zip
```

> Note: The name of the continuous release can be changed

Once this is done, each commit on master will result in updating the assets of the `continuous` release on GitHub to save the latest one.

![Screenshot of continuous release](GithubActions_continuous.png)

## Save releases artifacts

We have seen how to save the last artifact of a branch in a `continuous` release, but another case needs to be taken into account: the real releases.

It is useful when we release a project to save a Pharo image of this project with the version of the release.

This can be done with a new workflow file that will target releases:

```yml
name: Release

on:
  release:
    types: [created, edited]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      PROJECT_NAME: MyProject-${{ matrix.smalltalk }}
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    strategy:
      matrix:
        smalltalk: [ Pharo64-10, Pharo64-11 ]
    name: ${{ matrix.smalltalk }}
    steps:
      - uses: actions/checkout@v3
      - uses: hpi-swa/setup-smalltalkCI@v1
        with:
          smalltalk-version: ${{ matrix.smalltalk }}
      - run: smalltalkci -s ${{ matrix.smalltalk }}
        shell: bash
        timeout-minutes: 15
        
      # Here we zip the result of the build to be able to keep the artefacts
      - name: package
        run: |
          mv /home/runner/.smalltalkCI/_builds/* .
          mv TravisCI.image $PROJECT_NAME.image
          mv TravisCI.changes $PROJECT_NAME.changes
          echo ${${{ matrix.smalltalk }}} | sed -e 's/.*\-//g ; s/\..*//g ; s/$/0/' > pharo.version
          zip -r $PROJECT_NAME.zip $PROJECT_NAME.image $PROJECT_NAME.changes *.sources pharo.version
          ls
        
      - name: Release
        uses: softprops/action-gh-release@v1
        with:
          files: ${{ env.PROJECT_NAME }}.zip
```

This file looks a lot like the one we wrote in the previous section.

A few changes are to be noted. The is the name of the workflow to identify it easily in the Actions tab of Github.
The second is the target to build only on releases.

```yml
on:
  release:
    types: [created, edited]
```

And the last change is the action used after creating our Pharo archive.

```yml
      - name: Release
        uses: softprops/action-gh-release@v1
        with:
          files: ${{ env.PROJECT_NAME }}.zip
```

This action will add the files matching the $files: property to the assets of the release.

![Screenshot of releases](GithubActions_releases.png)

## Depending on the resources of your repository with GitBridge

It happens in some projects that we need resources to do some tests. In the past, it was common to save those resources as a string or a byte array directly in a method of the project.
This makes can have multiple drawbacks like making the management of the project harder, dropping Pharo's performances in code management, no real versioning of those resources…

Now that we can store our projects on git, an alternative is possible: Save your resources in your git repository and use file references in Pharo to access them.

To help with that, the project [GitBridge](https://github.com/jecisc/GitBridge) was created. 
This project helps one to access resources from the git repository and information from git directly from the Pharo image.

This project can be added as a dependency of your project with this spec:

```Smalltalk
    spec
    	baseline: 'GitBridge'
    	with: [ spec repository: 'github://jecisc/GitBridge:v1.x.x/src' ]
```

In order to create a GitBridge to your project, you first need to subclass `GitBridge` and to store your bridge in a package of your project.

```Smalltalk
GitBridge subclass: #MyProjectBridge
	slots: {  }
	classVariables: {  }
	package: 'MyProject'
```

This new bridge needs a class initialization like this one:

```Smalltalk
MyProjectBridge class>>initialize
	SessionManager default registerSystemClassNamed: self name
```

This will allow the bridge to reset some cache at the image startup.

Now that your bridge is created, if it finds an Iceberg repository associated with its local clone containing the package in which the bridge is defined, you will be able to use the bridge to access some resources.

For example, you can get a file reference to the git folder like this:

```Smalltalk
MyProjectBridge root
```

And this allows you to access your test resources.

Once your project is using `GitBridge`, you just need to be sure of two things in order for the CI to work. 
The first is to have the option `#registerInIceberg` to true in your smalltalkCI configuration.

```ston
SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'MyProject',
      #directory : 'src',
      #registerInIceberg : true
    }
  ]
}
```

And the second is to add a parameter to the checkout action of your workflow file in order to fetch the full history of git:

```yml
  steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: '0'
```

Once those steps are set up, your tests should be able to run and fetch resources from your git repository without trouble.
For more information, you can look at the [documentation of GitBridge](https://github.com/jecisc/GitBridge).

## Add your build artifacts to PharoLauncher

[Pharo launcher](https://pharo-project.github.io/pharo-launcher//) is a great tool to manage Pharo images, and here we are going to explain how to be able to get images of your project from it. 

> Note: In order to do this, you will need to have a continuous release and/or a release workflow setup as we explained earlier in this documentation.

Pharo launcher comes with a default set of sources to fetch Pharo images. It also allows one to add its own sources, and we will show here how to add your project as one of your own source.

It is doable thanks to the `mysources.list` of pharo-launcher file located in the `PhLUserTemplateSources sourcesFile` folder. If present, this file defines additional template sources beyond the official list of templates. At this time, there is no UI to add them.

To find the right folder:

* Open the Pharo Launcher
* Open a Playground (Ctrl + O, Ctrl + W)
* Execute `PhLUserTemplateSources sourcesFile`

You can now edit `mysources.list` in this folder to add the images of your project you wish to have in your Pharo launcher.

Here is how to add images from your continuous release:

```st
[
	PhLTemplateSource {
		#type : #URLGroup,
		#name : 'MyProject',
		#templates : [
			PhLTemplateSource {
				#type : #URL,
				#name : 'MyProject Pharo 10 - master',
				#url : 'https://github.com/MY_USERNAME/MY_PROJET_NAME/releases/download/continuous/MyProject-Pharo64-10.zip'
			},
			PhLTemplateSource {
				#type : #URL,
				#name : 'MyProject 11 - master',
				#url : 'https://github.com/MY_USERNAME/MY_PROJET_NAME/releases/download/continuous/MyProject-Pharo64-11.zip'
			}
		]
	}
]
```

And here is how to add images from a specific release, lets say `v1.4.3`:

```st
[
	PhLTemplateSource {
		#type : #URLGroup,
		#name : 'MyProject',
		#templates : [
			PhLTemplateSource {
				#type : #URL,
				#name : 'MyProject Pharo 10 - v1.4.3',
				#url : 'https://github.com/MY_USERNAME/MY_PROJET_NAME/releases/download/v1.4.3/MyProject-Pharo64-10.zip'
			},
			PhLTemplateSource {
				#type : #URL,
				#name : 'MyProject Pharo 11 - v1.4.3',
				#url : 'https://github.com/MY_USERNAME/MY_PROJET_NAME/releases/download/v1.4.3/MyProject-Pharo64-11.zip'
			}
		]
	}
]
```

You can then adapt those sources to what you need. Once it is done, you can click on the `New` button of the launcher and see a new source named `MyProject`.

## External ressources

Here are some resources on GitHub actions and Pharo:
- [https://badetitou.fr/blog/2020-11-30-Testing_pharo_with_github_actions](https://badetitou.fr/blog/2020-11-30-Testing_pharo_with_github_actions/)
- [https://badetitou.fr/blog/2022-10-28-test-your-moose-code-using-ci](https://badetitou.fr/blog/2022-10-28-test-your-moose-code-using-ci)
- [https://modularmoose.org/posts/2021-07-19-automatic-metamodel-documentation-generation](https://modularmoose.org/posts/2021-07-19-automatic-metamodel-documentation-generation)

Do not hesitate to do a PR to add more resources ;)


================================================
FILE: General/Glossary.md
================================================
# Pharo vocabulary
The Pharo community uses specific vocabulary to designate object oriented concepts, Pharo concepts and Pharo tools.

This page aims to provide disambiguation for the words belonging to this vocabulary.

## $a 
The character a. In Pharo strings are composed of characters, a character starts with a $. For unprintable characters such as tab, just send the message to the class e.g., `Character tab`.

## Binary message
A binary message is a [message](#message) composed of special character(s) where two objects are involved (the [receiver](#receiver) and one argument), which is the reason it is call binary. This is mostly used for arithmetic, comparison, and logical operations. For example, `+` is a binary message involving the receiver and the argument in parameter.

## Bootstrap
According to [wikipedia](https://en.wikipedia.org/wiki/Bootstrapping),

> "Bootstrapping usually refers to a self-starting process that is supposed to proceed without external input."

In the case of Pharo, [images](#image) are bootstrapped from the sources. Anyone can download the sources and [create their own custom Pharo image](https://github.com/carolahp/pharo/tree/candle). The Pharo [continuous integration server](https://ci.inria.fr/pharo-ci-jenkins2/job/Test%20pending%20pull%20request%20and%20branch%20Pipeline/) launch the bootstrap process each time a pull-request is merged into [pharo repository](https://github.com/pharo-project/pharo).
This seems to be a natural process but one has to know that up to Pharo 7.0, images were not bootstrapped. This means that, each version of Pharo was in fact a copy of the previous image with some additional changes.

## Browser
The browser is the tool for browsing and editing packages, classes and methods. In Pharo 6.1 and greater, the browser is called Calypso.

## Candidates
In the context of a method-call the candidates are the potential classes in the system that can receive the call. This list is computed from a static analysis of the source code.

## Changes (file)
The changesfile logs all source code modifications (especially all the changes you did while programming) since the [sources file](#sources) was generated. This facilitates a per-method history for diffs or reverting. It means that even if you did not manage to save the image file on a crash or you just forgot to, you can recover your changes from this file. A changes file is always coupled with an image file. They work as a pair.

> Note: Since Pharo 5, a project called Epicea implementing a new logging system has been introduced in the system. The long term goal of Epicea is to replace the changes file, but this objective has not been reached yet.

## Class-side
The class-side of a class refers to its meta-class. This meta-class contains methods that can be sent to the class directly.
For example, `#x:y:` method (which creates an instance of `Point` with arbitrary x and y coordinates) is held by the meta-class of `Point`.

In Pharo, both `Class` and `Metaclass` understand `#classSide` method.
For example:

```Smalltalk
Point classSide. "Point class"
Point class classSide. "Point class"
Point includesSelector: #x:y:. "false"
Point class includesSelector: #x:y:. "true"
```

The best way to understand what the class-side is, is to have a look at `#classSide` methods implementations:

```Smalltalk
Class>>#classSide
	^ self class
```

```Smalltalk
Metaclass>>#classSide
  ^ self
```

## Cog
Cog is the name of the [virtual machine](#virtual-machine) used by Pharo.
It is also used by other programming languages such as [Squeak](#squeak), Newspeak and Cuis.

## Context
A *Context* represent a program execution. It will store, for example, the `CompiledMethod` being currently executed, the receiver and arguments of the message that invoked this `CompiledMethod`, the temporary variables, the stack of calls until the moment of the execution, ...
In Pharo, you can use the keyword `thisContext` to interact with the current context of your code. It will return the `Context` object at the moment of the execution. This object is different on each method call.

## Debugger
The *Debugger* is a tool opened by the system when an exception is raised and never got caught. This tool allows the developer to interact with the execution [context](#context) that raised the error and its previous contexts. It lets the users inspect the objects present in this context and updates the code to fix the bug using the execution information as help.

## Dispatch
Dispatch is a technique used in object-oriented programming to delegate behavior using [polymorphism](#polymorphism). The goal is to define a concept that will change depending on the context. For example we can have an application with commands. When we need to execute the commands, instead of creating a switch/case, each object will implement its own behaviour on a method of the same name and we just need to call this method. 

## DNU
See [DoesNotUnderstand](#doesnotunderstand).

## DoesNotUnderstand
This name is used to describe the error that arises when a [message](#message) is sent to an object but the object does not understand it. It also happens that people use the "DNU" shortcut.

## Iceberg
*Iceberg* is git client integrated in the system since Pharo 7 (Pharo 6.1 contained a technical preview of the tool). It is a set of tools that allows one to handle git repositories directly from a Pharo image. Iceberg is the default repository manager for Pharo, allowing for smoother and faster integration of contributions, as well as better branch and version management.

## Image
A Pharo image is a snapshot of Pharo memory at any given moment.
This is the file where all objects are stored and as such, it’s a cross platform format.
An image file contains the live state of all objects of the system (including classes and compiled methods, since they are objects too) at a given point.
It can bee seen as a virtual object container.

## Implementors
For a given selector in the system, implementors are classes that have a method with this selector (they implement the selector). For example the implementors of the method `#banana` are all the classes containing a method named `#banana`.

## Inspector
The *Inspector* is a Pharo tool which allows one to inspect objects, see their current state, interact with them and display specific information depending on the object. It offers multiple views and it uses a Finder as a navigation. One particular feature is that you can use the evaluator tab to enter code, and evaluating it results in the opening of another pane to the right.

## Instance
An instance is a concrete realisation of a class.
One can send [messages](#message) to an instance.
These messages correspond to methods defined by the class related to the instance.
All instances of a class share the behaviour (methods) and structure ([slots](#slot)) defined by the class but two instances can hold different data in their [slots](#slot).

## Instance-side
The instance-side of a meta-class refers to its class. This class contains methods that can be sent to its instances.
For example, `#x` method (which returns the x coordinate of a point) is held by the class `Point`.

In Pharo, both `Class` and `Metaclass` understand `#instanceSide` method.
For example:

```Smalltalk
Point instanceSide. "Point"
Point class instanceSide. "Point"
Point includesSelector: #x. "true"
Point class includesSelector: #x. "false"
```

The best way to understand what the instance-side is, is to have a look at `#instanceSide` methods implementations:

```Smalltalk
Class>>#instanceSide
	^ self
```

```Smalltalk
Metaclass>>#instanceSide
  ^ self soleInstance
```

## Instance variable
See [slot](#slot).

## Keyword message
A keyword message is a [message](#message) where two or more objects are involved (the [receiver](#receiver) and the arguments). A message is composed of alphanumeric characters. The arguments are injected inside the message selector and must be preceded by a colon (`:`). For example, `between:and:` is a keyword message with a receiver and two arguments. It can be used like this: `13 between: 12 and: 14`.

## Late binding
*Late binding* (or *dynamic binding*) is a general mechanism in which methods or functions called are [looked up](#lookup) at run-time. This mechanism is the opposite of *early binding* that does the lookup at compilation-time and fixes all types of variables during that time.
More concretely, it means that in Pharo, when you send a [message](#message) to an object, the lookup of the method to execute is performed and then the method found by the lookup is executed. This simplifies the use of reflectivity since the user can invoke new methods without recompiling the whole application.

## Lookup
Method lookup is the name of the technique Pharo uses to find the method to execute when an object receives a [message](#message). It proceeds as follows: When a message is sent, methods in the [receiver](#receiver)'s class are searched for a matching method. If no match is found, the superclass is searched, and so on up the class chain. In the end, if no method is found, the object calls the method [`#doesNotUnderstand:`](#doesnotunderstand) with the message as a parameter.

## Message
A message represents an interaction between two objects.
A [sender](#sender) sends a message to a [receiver](#receiver) which will start a [lookup](#lookup).
A message is composed of two elements: the selector, which is the name of the method to lookup, and argument values which are the values of each argument of the method to execute once found by the lookup.
Three kinds of messages exists: [unary messages](#unary-message), [binary messages](#binary-message) and [keyword messages](#keyword-message).

## Message-send

## Monticello
*Monticello* is a distributed versioning system for [Squeak](#squeak) and Pharo code. It was the main versioning system until Pharo 6. It is now recommended to use [Iceberg](#iceberg).

## Object
The word object is used to refer to a particular [instance](#instance) of a [class](#class). "Object" and "instance" words are synonyms.

## Playground
The playground / workspace designate a code editor allowing one to run Smalltalk code that is not contained in a method.
This tool is useful to run small scripts that can be thrown after the execution.
If one needs to write a script that needs to be kept for a long time, it is better to right it as a class-method with the `<script>` pragma.

## Polymorphism

## Pragma
Pragmas are annotations on methods. They are used to attach additional properties to the methods to make those methods easily collectable through reflectivity and to ease the creation of special handlings.
A page dedicated to pragmas is available [here](Pragmas.md).

## Primitive
A primitive is a method for which the source code is not written in Smalltalk but directly in C code. From the inside of the image, those methods contain a `<primitive:>` pragma.

Some methods holding this primitive pragma also contain source code written in Smalltalk. For these methods, first the C version of the method is tried but if the implementation in C is not provided by the VM for some reason, Pharo falls back to the Smalltalk implementation.

## Protocol
In Pharo, each method belongs to a protocol. A protocol has a name and allows one to group methods that are related. For example, the protocol `accessing` is widely used in the system to hold accessor and mutator methods.

## Receiver
The receiver of a [message](#message) send is the instance of a class implementing the method corresponding to the message sent receiving this message.

## Selector
A selector corresponds to the signature of a method in the system. Since Pharo is not statically typed, the selector of a method is simply a Symbol. On a CompiledMethod, it is possible to send the `#selector` message to retrieve this Symbol.

## Self
Self is the [receiver](#receiver) of a [message](#message) an object sends to itself. This means that the [lookup](#lookup) of a method send will start by the sender of this message then, if not found, it will proceed with its superclass.

## Sender
The sender of a [message](#message) is the object that will send a message to another object. In case the [receiver](#receiver) of a message is [self](#self), then the sender is equal to the receiver.

## Senders
For a given selector in the system, senders are the methods sending a message with this selector. For example, the senders of the method `#banana` are all the methods sending the message `#banana` in their code.

## Sista 
Sista is the name of a [virtual machine](#virtual-machine) with adaptive optimisations such as speculative inlining (meaning that the Virtual machine tries to guess the type of receiver and the arguments. Based on this, it heavily optimises the code at runtime, in case of a wrong guess it de-optimises the code). It showed better performance but is still currently under development. It is not yet production-ready.

## Slang
The term "Slang" refers to a subset of the Smalltalk language that can be translated to C (or other language, such as Javascript). It is mainly used to develop the [Cog](#cog) virtual machine. It allows one to develop the virtual machine using Pharo tools and generates C.

## Slot
Instance variables are reified in Pharo, which means they are real objects that can be manipulated just like any other object.
Because of that, the name *slot* has been given to the general concept of an instance variable in Pharo.
In practice, most of the slots in classes of the system are `InstanceVariableSlot`.
One can create a new kind of slot by subclassing `Slot` class (see [this blogpost](https://medium.com/@juliendelplanque/typed-slots-for-pharo-98ba5d5aafbe) as an example).

## Smalltalk
Smalltalk is an object-oriented, dynamically typed reflective programming language with multiple implementations. Some implemenations include [Squeak](#squeak), VisualWorks, Gemstone, VA Smalltalk and many others. Pharo started as an implementation of Smalltalk and is still very close to it.

## Sources (file)
The sources file contains source code of Pharo. Sources file is important because the image file format stores only objects including compiled methods and their bytecode and not their source code. Originally, a new sources file was generated once per major release of Pharo. Now, Pharo changed its production mechanism to be [bootstraped](#bootstrap) and generates a new sources file for each Pharo image produced.

## Spur
Spur is the name of the current object representation in memory of Pharo used by the [virtual machine](#virtual-machine). This representation is used since Pharo 5 and was introduced to improve performances (by 30% compared to the previous implementation) and prepare Pharo to run in 64bits.

## Squeak
Squeak is a dialect of [Smalltalk](#smalltalk). Pharo started as a fork of Squeak and both still share the same [virtual machine](#virtual-machine).

## Super
Super is the [receiver](#receiver) of a [message](#message) an object send to itself, but on the contrary of [self](#self), the method lookup will start in the superclass of a receiver. Super is a unique way for the class to add behavior to the inherited methods and not just replace them.

## Traits
Traits are pure units of behavior that can be composed to form classes or other traits. The trait composition mechanism is an alternative to multiple or mixin inheritance in which the composer has full control over the trait composition. It enables more reuse than single inheritance without introducing the drawbacks of multiple or mixin inheritance.
A page dedicated to traits is available [here](Traits.md).

## Unary message
An unary message is a [message](#message) where only the [receiver](#receiver) of the message will be required, which is the reason it is called unary. This means that the message will have no argument. For example, `#factorial` is an unary message that will only require the number receiving the message.

## VM
See [virtual machine](#virtual-machine).

## Virtual Machine
The virtual machine of Pharo is the execution engine. It takes Pharo bytecode that is generated each time the user compiles a piece of code, converts it to machine code and executes it. The VM is different for each platform running Pharo (windows, OSX, linux, arm, 32/64bits) and allows the other part of Pharo to be platform independent.

## Workspace
Workspace is the previous name of the [Playground](#playground).


================================================
FILE: General/HowToRunPharoFromCommandLine.md
================================================
# Getting Pharo running from the command line

Here are some simple steps to get Pharo ready from the command line. The script 
assumes that you have a bin folder in your home directory. 

The following script downloads the stable vm version of Pharo 80. Check the web page [https://get.pharo.org/64/](https://get.pharo.org/64/)
to get the possible choices. 

```bash
mkdir bin
cd bin
curl https://get.pharo.org/64/vm80 | bash
```

This script creates two scripts, pharo-ui and pharo-vm both using the contents of the Pharo folder that is also created. 

Once installed you can execute pharo as follows: 

```bash
./pharo-ui Pharo8.image 
```

If you do not want Pharo displaying a user interface as a pop-up, you can invoke it as follows: 

```bash
./pharo Pharo8.image 
```


================================================
FILE: General/IcebergOnWindows.md
================================================
# Iceberg on Windows Workaround

- [Make path to the Pharo Image shorter](#make-path-to-the-pharo-image-shorter)
- [Convert the repository to the Tonel format](#convert-the-repository-to-the-tonel-format)

Long file names in Windows raise the error message  “Failed to stat file ‘filename’: The filename or extension is too long”.

The Windows problem with long filenames is a constraint of [libgit](https://libgit2.org/libgit2/#HEAD) library that is used in Pharo (Iceberg accesses git through this exact library). It occurs because FileTree format tends to have long paths and was one of the main drivers in creating the Tonel format. This error can occur, for example, when you are trying to clone your Pharo fork on Github into Pharo local. There are two possible ways to fix it:

1. Make path to Pharo Image short.
2. Convert repo to Tonel format — in Iceberg there is a menu item under one of the Extras menus.

Here’s more about them:

## Make path to the Pharo Image shorter

If you are simply using a standalone Pharo [download](http://pharo.org/download/#standalone), you can just move your image and VM a few folders up. However, if you are using [Pharo Launcher](http://pharo.org/download/), you have to access the settings, to change where it stores images it will create in the future, as well as move all the existing images and VMs up. Here’s how to do it.

In Pharo Launcher, in the bottom right corner you can see a button ‘open settings’ — click on it.

![alt text](https://github.com/myroslavarm/pharo-wiki/blob/patch-1/General/win_2.png)

In the settings, if you expand the ‘Pharo Launcher’ tab you can see the following options:

![alt text](https://github.com/myroslavarm/pharo-wiki/blob/patch-1/General/win_3.png)

In the first, third and fourth options, change directories without disrupting the dependencies (images in ‘images’, template sources one folder up, etc). When you change the paths, the upper right corner of each of the text boxes will be yellow, which means unsaved changes (that is also the logic inside Pharo). You have to position your cursor in each of the text boxes and press (ctrl+s) to save the changes.

Don’t forget that this section only means images and VMs it will create in the future, so you should also manually move your already existing images and VMs to the same folder you listed. 

Now, everything should work!

## Convert the repository to the Tonel format

Note re FileTree/Tonel: A FileTree represents a hierarchy of files. [Tonel](https://github.com/pharo-vcs/tonel) is a file-per-class format — class and all methods are stored in a single file, which is better than having a file for each method because the code is easier to read outside of Pharo and it creates less files on the hard drive. Tonel also prevents some trouble with git on Windows due to number of files and subdirectory depth that create path exceeding windows limit.

If you are using an older version of Pharo, you need to download Tonel by running the code below in a playground (in Pharo 7 and 8 it comes by default):

```Smalltalk
Metacello new
  baseline: 'Tonel';
  repository: 'github://pharo-vcs/tonel:v1.0.12';
  load.
```

> Note: In Pharo 7 and 8 you don’t need any kind of script to convert to Tonel — there’s a UI option available. But in Pharo 6.1 you need to upgrade Iceberg first, and Tonel will come with it. Link with the script [here](https://github.com/pharo-vcs/iceberg/#for-pharo-61).

With Tonel loaded, if you go to Iceberg repositories and right-click on the specific repository, you can go to ‘extra’ category and click on ‘convert repository sources to tonel’ button. It will migrate the code for you.

![alt text](https://github.com/myroslavarm/pharo-wiki/blob/patch-1/General/win_4.png)

> Note: this option is only possible if the repository isn’t already in the Tonel format. So if your problem is cloning the Pharo fork (Pharo repo is partially Tonel, partially Filetree), then the only option that will actually solve it, is  shortening the path.




================================================
FILE: General/ImageFileFormat.md
================================================
# Image file format
Pharo image is a binary file containing a snapshot of the runtime.
However, there is only a little documentation about its structure (how information is encoded as bytes).
This page is an early work to document the binary format of Pharo images.

- [Determinate the format of an image](#determinate-the-format-of-an-image)
- [Image format accross Pharo versions](#image-format-accross-pharo-versions)

## Determinate the format of an image
Each image has a format. The format can be retrieved by reading the 4 first bytes of an image file.
These bytes encode an integer from least significant to most significant byte (little-endian).

On MacOS, you can use `od` shell command to show these 4 bytes:

```bash
od -t x1 -N 4 Pharo.image
```

You will get an output as follow:

```
0000000    b5  09  01  00                                                
0000004
```

Which correspond to `68021` in decimal.

## Image format accross Pharo versions

| Pharo version                | Image format code | Image first 4 bytes (hex) |
|:-----------------------------|:------------------|:--------------------------|
| version <= 1.3               | 6504              | 68  19  00  00            |
| 1.3 < version <= 5.0-preSpur | 6505              | 69  19  00  00            |
| version (32bits) >= 5.0      | 6521              | 79  19  00  00            |
| version (64bits) >= 5.0      | 68021             | b5  09  01  00            |


================================================
FILE: General/Inspector.md
================================================
# Inspector

*Written based on Pharo 12.0.0 - Build information: Pharo-12.0.0+build.710.sha9e02d19b14a8ecb9cbd45d6ba0166d3b92202c3c (64 Bit)*

The Inspector is a tool that is used to look at an object. In Pharo, inspecting an object means opening this tool. It allows to navigate the object structure and look at the state of the variables, but can show other information.

You can inspect the result of an execution by selecting the code and using the shortcut`Cmd/ctrl + i` or `right-clic + "Do & inspect it"`. This will execute the code and open an inspector on the result. 


The  [🐥 Learn Keyboard Shortcuts \[W1-Live D\]](https://www.youtube.com/watch?v=7YTsys2qxMU&list=PL2okA_2qDJ-kCHVcNXdO5wsUZJCY31zwf&index=10&t=133s) video from the [Pharo MOOC](https://mooc.pharo.org/) demonstrate how to open it.

By inspecting `1/3` we get the following inspector :

![Raw tab](Inspector_raw_tab.png)


## A first look at the inspector

![Raw tab areas](Inspector_raw_tab_areas.png)

The tree framed areas in the next pictures are :
1. This text starts with the **class** of the inspected object. Here we have an instance of Fraction.
2. This is the raw view object. It shows the internal state of the object. Here the fraction as a `numerator` instance variable holding the value 1, and a `denominator` instance variable holding the value 3. 

This is a tree list. When you see the small grey triangle on the left side, by clicking it you can unfold the state of the object inside the instance variable. 
By clicking on an instance variable you can also open a new inspector pane.

This is recursive : if you click on more variables, more pane will open. By default only the last two panes are visible at any time. You can use the small rectangles at the bottom of the window to navigate in the opened pane. You can also choose how many panes and showing at the same times and which one. 

Here is a small demonstration :
![Navigating in the inspector](Inspector_pane_navigation.gif)

3. This last area is the evaluator. In this area you can write expression and evaluate them like you would do it in the playground. In a given evaluator, `self` is referring to the inspected object. This can be seen in the raw view above the evaluator showing the value of the `self` variable.

## The pane tool bar

Each inspector pane has the following toolbar :


![Raw tab areas](Inspector_pane_toolbar.png)

- The **last button** allows one to open a browser on the class of the inspected object. It can be used to check for available methods to use in the evaluator
- The **green glasses** button opens another inspector window on the current object
- The **circling arrows** button allow to refresh the crurent view of the object. Fields of an object are not updated live, so if the object is modified from elsewhere, the new values will only show if the refresh button is used.
- The **triangle button** is related to object-centric debugging. It allows one to put breakpoints on state access (read and/or write) of a specific object.The following animation shows how to put a breakpoint on writing an instance variable, the `Breakpoints` tab listing breakpoints on the current object and how to deactivate one :

![Breakpoints](Inspector_breakpoints.gif)

## The Meta tab : searching for methods and class hierarchy
The `Meta` tab is the last one that is available on most objects.
On the left it shows the class hierarchy of the current object's class and on the right the methods available. Clicking on parent classes in the hierarchy will show methods implemented in this class on the right. Selecting a method will display its source code at the bottom of the tab.


![Meta tab](Inspector_meta_tab.png)

## Creating custom tabs

If you used the inspector a bit, you might have noticed that some objects have additional tabs showing up in the inspector.
For example both Floats and Integer have their first tabs showing different representations of the numbers :

![Inspecting numbers](Inspector_numbers_tabs.png)

Another example is the `FileReference` class. When a file reference is inspected, according to the type of the file, different tab show up with relevant information.

Creating a new tab requires being able to build UI elements called presenters with spec 2. For more explanation on how to build a spec 2 presenters, please see the [Spec 2 documentation](https://github.com/SquareBracketAssociates/BuildingApplicationWithSpec2/tree/master).

For people building visualisation, [Roassal 3](https://github.com/ObjectProfile/Roassal3) visualisations can be embedded in a spec 2 presenter by sending the `asPresenter` message to an instance of RSCanvas.

The following sections will explain how to add a few additional tabs to instances of `OrderedCollection`. This class already as a custom tab showing the list of its items which is defined by its superclass `Collection`.

### Adding a tab with text

Let's add a first tab containing a text describing the first element of the collection. Define the following method :

```Smalltalk
OrderedCollection << inspectionFirstElement

	<inspectorPresentationOrder: 1 title: 'First Element'>

	^ SpTextPresenter new text: 'The first element is ', self first asString; beNotEditable; yourself
```
`<inspectorPresentationOrder: 1 title: 'First Element'>` is a pragma that is detected when creating an inspector on an object. When creating an inspector on an instance of `OrderedCollection`, this method will now be used to generate a tab. The title of the tab will be `First Element`, it will be in position 1 in the order of tabs.

The content of the tab is returned by the method. Here we are creating a text presenter with the content we want and we specify it should not be editable.

This gives us the following result :

![First element tab](Inspector_expension_first_element.png)
We notice that our new tab is in second position. This is because in `Collection<<inspectionItems:` (the method defining the Items tab) the order parameter is 0.

### Adding a tab with a table and conditions on when to display it

Let's create a new tab that will display a table only when the collection contains only numbers. It will show each number and the results of 2 times that number.

First let's create the tab with the table:
```Smalltalk
OrderedCollection << inspectionMultipliedByTwo

	<inspectorPresentationOrder: 10 title: 'Multiply by 2'>
	| presenter |
	presenter := SpTablePresenter new
		             addColumn:
			             ((SpStringTableColumn
				               title: 'Item'
				               evaluated: #yourself)
				              width: 30;
				              yourself);
		             addColumn: (SpStringTableColumn
				              title: 'Multiply by 2'
				              evaluated: [ :each | each * 2 ]);
		             items: self;
		             beResizable;
		             yourself.
	^ presenter
```
If we inspect a collection of numbers we get the following tab :
![Mutliplied by 2 tab](Inspector_expension_multiplied_by_two.png)

However if the collection contains elements that are not numbers, the tab crashes and looks like a red rectangle. By defining a method with the name `<name of the method defining the tab>Context:` we can specify when we want to activate a given tab.
For example :
```Smalltalk
OrderedCollection << containsOnlyNumbers 
	^ self allSatisfy: [ :each | each isNumber  ]


OrderedCollection << inspectionMultipliedByTwoContext: aContext
	^ aContext active: self containsOnlyNumbers.
```
Will ensure that the tab will be displayed only when there is only number in the collection.



## Adding a raw view of a specific element of the collection and removing the evaluator

We can also add a tab showing the raw view of the max value :
```Smalltalk
OrderedCollection << inspectionIMaxValue
	<inspectorPresentationOrder: 5 title: 'Max Value'>
	^ StRawInspectionPresenter on: self max.

OrderedCollection << inspectionIMaxValueContext: aContext
	^ aContext active: self containsOnlyIntegers.
```
![Inspect max value tab](Inspector_expension_max.png)

However as we can see above, the self in the evaluator does not match the self in the max value which is confusing so we will hide the evaluator.

```Smalltalk
OrderedCollection << inspectionIMaxValueContext: aContext
	aContext withoutEvaluator.
	^ aContext active: self containsOnlyIntegers.
```
By reinspecting the same collection we get :
![Removing the evaluator](Inspector_expension_max_without_evaluator.png)

### How to add Roassal charts ?
As said above, Roassal, allow one to build visualisations.
The library includes some common graphs like the histogram for example.
Let's add a histogram of the values if there are only numbers in the collection :

```Smalltalk

OrderedCollection << inspectionIntegerHistogram

	<inspectorPresentationOrder: -1 title: 'Histogram'>
	| plot |
	plot := RSHistogramPlot new x: self.
	^ plot asPresenter


OrderedCollection << inspectionIntegerHistogramContext: aContext 

	aContext active: self containsOnlyIntegers.
	aContext withoutEvaluator.
```
By inspecting `{ 1 . 1 . 3 . 2 . 5 . 2. 2 . 1. 9. 3 . 2. 2. 5 . 7 . 7 . 8  } asOrderedCollection` we get :
![Histogram tab](Inspector_expension_histogram.png)




================================================
FILE: General/InterestingsToKnowForBeginners.md
================================================
# Interesting things to know for beginners

This page will expose different things that might be interesting to know for beginners. Tools, API, shortcuts...

The goal is to ease the use of Pharo for beginners.

- [API](#api)
- [Evaluatable objects (Blocks and Symbols)](#evaluatable-objects--blocks-and-symbols-)
- [Tools](#tools)
  * [Calypso System Browser](#calypso)
- [Flags](#flags)
- [Useful pragmas](#useful-pragmas)
  * [Modify IDE](#modify-ide)
  * [Influence execution of methods](#influence-execution-of-methods)
  * [Influence Debugger](#influence-debugger)

## API

The Pharo API is extensive. In this section we will explain various methods existing in Pharo that have proven to be useful in our experience.

**String class>>#streamContents:**

String concatenation can be costly because it will create a new string instance and copy the content of the two strings at each concatenation. To make it more efficient, Pharo includes a method to create a String via a stream:

```Smalltalk
'This is a ', 'string concatenation ' , 'that is not really' , ' ' , ' efficient'.

String streamContents: [ :aStream | aStream << 'This is a '<< 'string concatenation ' << 'that is ' << ' ' << ' efficient' ]
```

## Evaluatable objects (Blocks and Symbols)
Pharo's Blocks and Symbols have an interesting property: they are polymorphic through `#value:` and `#cull:` methods.

For example, the two code snippets below are equivalent:

```Smalltalk
#class value: Object new
```

```
[ :o | o class ] value: Object new
```

They both return the class of an object.

This means that for methods taking a one-argument block as a parameter, this block can be replaced by a symbol. The effect is that the unary method named by the symbol will be executed with the object as the receiver.

The difference between `#value:` and `#cull:` is that `#value:` requires a parameter when `#cull:` can work with or without a parameter.

The common usage of this feature is via iterators. For example, if you want to collect the result of the `name` method of all objects in a collection you can either do:

```
objectCollection collect: [ :o | o name ].
```

or

```
objectCollecton collect: #name
```

The second way is shorter and often more readable.

## Tools

### Calypso (System browser)

- Display the differences between two methods
	* Click on a method
	* Hold down the `SHIFT` key
	* Click on the second method
	* Click on the tab Diff to see the differences
	
- Editing multiple methods side by side
	* Click on a method
	* Hold down the `CTRL` key
	* Click on all the methods you want to edit. 
	* Tabs are displayed with the source code of the methods selected.

## Flags

It is possible to "flag" methods in Pharo in order to be able to retrieve them later. This can be done by sending the `#flag:` message to self with a symbol as parameter which is the flag to be used.

Commonly used flags are:
- `#todo` to mark code that needs work to be done.
- `#hack` to mark hackish code.
- `#broken` to mark broken code.
- `#clean` to mark code that needs cleaning.
- `#toCheck` to mark code that should be checked later.
- `#pharoX` to mark code present for compatibility with `X` being the version of Pharo.

Flags will not modify the execution of a method. Flags are just used to tag methods.

For example, the method below will return `42` if executed as if there was no call to `#flag:` method.

```
myUnfinishedMethod
	self flag: #TODO. "Some process to be done here."
	^ 42
```

To retrieve methods for which you set flag(s), just search for senders of your flag. For example, to retrieve methods flagged with `#todo`, either inspect the result of the following script: `#todo senders` or just select the symbol and press Meta+N (shortcut for "Browse senders").

## Useful pragmas

Pragmas allow one to tag methods. They are similar to Java's annotations. Some pragmas allow the developer to modify the IDE or to influence execution of methods. This section presents some of these useful pragmas.

### Modify IDE

- `<script>` for class-side methods, adds a button next to the method name in the IDE. This button, when clicked, executes the method.
- `<script: 'Smalltalk code to run'>` is similar to `<script>` but the button executes the Smalltalk code held by the string provided as parameter to the pragma.
- `<sampleInstance>` for class-side methods, adds a button next to the method name in the IDE. When clicked, the method is executed and an inspector is opened on its result.
- `<worldMenu>` for class-side methods, add a menu entry in the Pharo menu. The method with this pragma should take a builder as a parameter. You can browse the senders of the `worldMenu` pragma to find the API.
- `<systemsettings>` for class-side methods, add an entry in the Pharo settings. The method with this pragma should take a builder as a parameter. You can browse the senders of the `systemsettings` pragma to find the API.
- `<haltOrBreakpointForTesting>` should be used in methods using breakpoints that should not be listed in the Breakpoint browser. For example, it can be used in examples using breakpoints to highlight a feature of the example.

### Influence execution of methods

- `<expectedFailure>` for instance-side methods of subclasses of `TestCase`, will make the test green when it is failing. But, although we expect that the test will fail, a success of the test (i.e. not assertion missed) will show as a failure.

### Influence Debugger
- `<debuggerCompleteToSender>` allows one to tell the debugger to open itself on the method that sends the message corresponding to the method holding the `<debuggerCompleteToSender>` pragma.

For example, let us consider these two methods:
```st
foo
	<debuggerCompleteToSender>
	Error signal: 'foo'
```

```st
fooCaller
	self foo
```

Because of the `<debuggerCompleteToSender>`, when `#fooCaller` is executed, the debugger will show `#fooCaller` method source code.
If the pragma was not there, the debugger would show `#foo` method source code.


================================================
FILE: General/Layout.md
================================================
# Mohpic's Layouts

The Morphic Library of Pharo is a low level UI framework. This page aims at describing how to layout morphes together.

- [Mohpic's Layouts](#mohpic-s-layouts)
  * [Row layout](#row-layout)
  * [Table Layout](#table-layout)
  * [Stack Layout](#stack-layout)
  * [Proportionnal layout](#proportionnal-layout)
  * [Annexe](#annexe)


## Row layout

This layout displays a morph's submorphs horizontally aligned.
By default, the submorphs display start at the topLeft corner of the morph.
With this layout, the submorphs are display in a array. This array associate a submorph with a cell of the array.
The size of a cell in Y depends of the max size of the morph in Y. However, the length in X of a cell depends of the size of the submorph who are displayed in this cell.
We modify the display of the submorph with several attribut :
- `cellPositioning` takes several values : center, bottomLeft, bottomRight, topLeft, topRight. This value allow to modify the display of the submorphs.
- `cellInset` : set a space between each cell of the morph, it takes an integer.
- `extent` : set the size of the morph, it takes a point.
- `hResizing` : allows to modify a morph horizontally. It takes several value : shrinkWrap, spaceFill, rigid.
  - `rigid` allows to not modify the morph
  - `shrinkWrap` resizes the morph to fit the frame of his submorph
  - `spaceFill` fills the empty space with this morph
- `vResizing`: allows to modify a morph vertically. It takes the same value as hResizing.

Example 1 : Row layout with two morphs

![alt text](layout_screenshot/RowLayoutExampleWithTwoMorph.png)
```st
| m1 m2 m3|
m1 := Morph new layoutPolicy: RowLayout new; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.`
```
Example 2 : Row layout with three morphs

![alt text](layout_screenshot/RowLayoutExampleWithThreeMorph.png)
```st
| m1 m2 m3 m4|
m1 := Morph new layoutPolicy: RowLayout new; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow.
m4 := Morph new color: Color purple.
m1 addMorph: m2.
m1 addMorph: m3.
m1 addMorph: m4.
m1 openInWorld.
```
Example 3 : Row layout with two morphs with cellPositioning : bottomLeft

![alt text](layout_screenshot/RowLayoutExampleWithTwoMorphCellPositionBottomLeft.png)
```st
| m1 m2 m3|
m1 := Morph new color: Color blue; layoutPolicy: RowLayout new;extent: (200@200);cellPositioning: #bottomLeft; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow; extent: (100@100); yourself.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld .
```
Example 4 : Row layout with two morphs with cellPositioning : center

![alt text](layout_screenshot/RowLayoutExampleWithTwoMorphCellPositionCenter.png)
```st
|m1 m2 m3|
m1 := Morph new color: Color blue; layoutPolicy: RowLayout new; extent: (200@200); cellPositioning: #center; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow; extent: (100@100); yourself.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld .
```

Exemple 5 : Row layout example with two morphs with cellPositioning : topLeft

![alt text](layout_screenshot/RowLayoutExampleWithTwoMorphCellPositionTopLeft.png)
```st
|m1 m2 m3|
m1 := Morph new color: Color blue; layoutPolicy: RowLayout new; extent: (200@200); cellPositioning: #topLeft; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow; extent: (100@100); yourself.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld .
```

Exemple 6 : Row layout with hResizing and vResizing : spaceFill

![alt text](layout_screenshot/RowLayoutwithvResizingAndhResizingAtSpacefillForOneMorph.png)
```st
| m1 m2 m3|
m1 := Morph new layoutPolicy: RowLayout new; yourself.
m1 extent: 250@250.
m2 := Morph new color: Color green.
m3 := Morph new color: Color purple.
m2 vResizing: #spaceFill.
m2 hResizing: #spaceFill.
m3 extent: 100@100.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
```

Exemple 7 : Row layout with hResizing and vResizing : shrinkWrap

![alt text](layout_screenshot/RowLayoutwithvResizingAndhResizingAtshrinkWrap.png)
```st
| m1 m2 m3|
m1 := Morph new layoutPolicy: RowLayout new; yourself.
m1 vResizing: #shrinkWrap.
m1 hResizing: #shrinkWrap.
m1 extent: 250@250.
m2 := Morph new color: Color green.
m3 := Morph new color: Color purple.

m3 extent: 100@100.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
```

## Table Layout

The layout is processed like this:
For computing the new layout for the children of any morph, we start with an initial rectangle which is provided as a reference.

Step 1: The first step of this layout computation is to compute the minimum extent each of our children can have. The minimum extent is mapped through both the local layout frame of the morph (for relative positioning) and the global layout frame (for insets, such as cursor indication) to obtain the minimal size required for each cell.

Step 2: Based on the cell sizes, the number of cells we can put into each row and column is computed. For equal spacing, the maximum size of the cells is taken into account here.

Step 3: Based on the row/column sizes, we compute the extra space which should be added to each row/column. For:
- `#leftFlush/#topFlush` - we add all extra space add the end
- `#rightFlush/#bottomFlush` - we add all extra space at the start
- `#centering` - we add 1/2 of the extra space at start and end
- `#justified` - we distribute the space evenly between the morphs
> NOTE: If any #spaceFill morphs are encountered during this step, #justified is implied and the space is exclusively and equally distributed between those #spaceFill morphs. This is for backward compatibility and should *never* be necessary in the new regime.

Step 4: The morphs are placed in the computed cells and the extra space is distributed as necessary. Placing the submorphs is done by mapping through the global and the local layout frame as requested.

Start point:
=> bounds: new rectangle for the morph.

Compute basic arrangement of morphs:
=> For each submorph compute minExtent
- if global layout frame inset in global layout frame
- if local layout frame inset in local layout frame
=> Compute number of morphs per, width and height of row/column
- if equal spacing based on max size
=> Compute extra space per row/column
- if centering = #justified; distribute space equally
- if centering #leftFlush/#topFlush (-1) add start extra
- if centering #rightFlush/#bottomFlush (1) add end extra
- if centering #centered add 1/2 extra to start/end
<extra space must be float and rounded accordingly!>
=> Place morphs in appropriate cells
- if global layout frame inset in global layout frame
- if local layout frame inset in local layout frame
<will likely cause #layoutChanged by submorphs>

Distribute morphs in row/column:

=> Compute the max length of each row/column

Example 1 : Table layout with two morphs

![alt text](layout_screenshot/TableLayoutExampleWithTwoMorph.png)
```st
|m1 m2 m3|
m1 := Morph new layoutPolicy: TableLayout new; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
```

Example 2 : Table layout with three morphs

![alt text](layout_screenshot/TableLayoutExampleWithThreeMorph.png)
```st
|m1 m2 m3 m4|
m1 := Morph new layoutPolicy: TableLayout new; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow.
m4 := Morph new color: Color purple.
m1 addMorph: m2.
m1 addMorph: m3.
m1 addMorph: m4.
m1 openInWorld.
```

Exemple 3 : Table layout with two morphs with cellPositioning : center

![alt text](layout_screenshot/TableLayoutExampleWithTwoMorphWithCenteringMorph.png)
```st
|m1 m2 m3|
m1 := Morph new color: Color blue; layoutPolicy: TableLayout new; extent: (200@200); cellPositioning: #center; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow; extent:  (100@100); yourself.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
```

Exemple 4 : Table layout with two morphs with cellPositioning : topLeft

![alt text](layout_screenshot/TableLayoutExampleWithTwoMorphWithTopLeftMorph.png)
```st
|m1 m2 m3|
m1 := Morph new color: Color blue; layoutPolicy: TableLayout new; extent: (200@200); cellPositioning: #topRight; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow; extent: (100@100); yourself.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
```

Exemple 5 : Table layout with two morphs with cellPositioning : topRight

![alt text](layout_screenshot/TableLayoutExampleWithTwoMorphWithTopRightMorph.png)
```st
|m1 m2 m3|
m1 := Morph new color: Color blue; layoutPolicy: TableLayout new; extent: (200@200); cellPositioning: #topLeft; yourself.
m2 :=  Morph new color: Color green.
m3 := Morph new color: Color yellow; extent: (100@100); yourself.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
```

Exemple 6 : Table layout with vResizing and hResizing : shrinkWrap.

![alt text](layout_screenshot/TableLayoutWithverticalandHorizontalShrinkwrapResizing.png)
```st
| m1 m2 m3 m4|
m1 := Morph new layoutPolicy: TableLayout new; yourself.
m1 vResizing: #shrinkWrap.
m1 hResizing: #shrinkWrap.
m1 extent: 1500@1500.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow.
m4 := Morph new color: Color purple.
m4 extent: 100@100.
m1 addMorph: m2.
m1 addMorph: m3.
m1 addMorph: m4.
m1 openInWorld.
```

Exemple 7 : Table layout with vResizing and hResizing : spaceFill

![alt text](layout_screenshot/TableLayoutWithVResizingAndhResizingAsSpacefill.png)
```st
| m1 m2 m3|
m1 := Morph new layoutPolicy: TableLayout new; yourself.
m1 extent: 250@250.
m2 := Morph new color: Color green.
m3 := Morph new color: Color purple.
m2 vResizing: #spaceFill.
m2 hResizing: #spaceFill.
m3 extent: 100@100.
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
```

Exemple 8 : Table layout with wrapCentering : center

![alt text](layout_screenshot/TableLayoutWithWrapCenteringCenter.png)
```st
| m1 m2 m3 |
m1 := Morph new layoutPolicy: TableLayout new; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow; layoutPolicy: TableLayout new; yourself.
m1 extent: 200@200.
m1 wrapCentering: #center.
m1 addMorph: m2.
m3 extent: (100@100).
m1 addMorph: m3.
m1 openInWorld.
```

Exemple 9 : Table layout with wrapCentering : bottomRight

![alt text](layout_screenshot/TableLayoutWithWrapCenteringbottomRight.png)
```st
| m1 m2 m3 |
m1 := Morph new layoutPolicy: TableLayout new; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow; layoutPolicy: TableLayout new; yourself.
m1 extent: 200@200.
m1 wrapCentering: #bottomRight.
m1 addMorph: m2.
m3 extent: (100@100).
m1 addMorph: m3.
m1 openInWorld.
```

Exemple 10 : Table layout with wrapCentering : topLeft

![alt text](layout_screenshot/TableLayoutWithWrapCenteringtopLeft.png)
```st
| m1 m2 m3 |
m1 := Morph new layoutPolicy: TableLayout new; yourself.
m2 := Morph new color: Color green.
m3 := Morph new color: Color yellow; layoutPolicy: TableLayout new; yourself.
m1 extent: 200@200.
m1 wrapCentering: #topLeft.
m1 addMorph: m2.
m3 extent: (100@100).
m1 addMorph: m3.
m1 openInWorld.
```

## Stack Layout

Unstack the submorphs at the center of the morph in default.
It could be a problem if the last submorph unstack was bigger than the other submorph, because the last one was display on the other.
It takes several attribut but the most relevant attribut was :
- cellPositioning
- extent
cellPositioning set the point of reference to display morph. For example, if the value was center, the morphs were gonna display with the center, if the value was : topRight, they gonna stack on the top right corner of parent morph

Example 1 : Stack layout with two morphs with lower morph extent

![alt text](layout_screenshot/StackLayoutExampleWithTwoMorphWithLowerMorphExtent.png)
 ```st
|m1 m2 m3|
m1 := Morph new layoutPolicy: StackLayout new; yourself.
m2 :=  Morph new color: Color green; extent: (100@100); yourself.
m3 := Morph new color: Color yellow .
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
```

Example 2 : Stack layout with two morphs with upper morph extent

![alt text](layout_screenshot/StackLayoutExampleWithTwoMorphWithUpperMorphExtent.png)
 ```st
|m1 m2 m3|
m1 := Morph new layoutPolicy: StackLayout new ; yourself.
m2 :=  Morph new color: Color green.
m3 := Morph new color: Color yellow; extent: (100@100); yourself .
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
 ```
Exemple 3 : Stack layout with two morphs with cellPositioning : topRight

![alt text](layout_screenshot/StackLayoutExampleWithTwoMorphCellPositioningTopRight.png)
```st
|m1 m2 m3|
m1 := Morph new layoutPolicy: StackLayout new; cellPositioning: #topRight; yourself.
m2 :=  Morph new color: Color green; extent: (100@100); yourself.
m3 := Morph new color: Color yellow .
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.  
```

Exemple 4 :  Stack layout with two morphs with cellPositioning : bottomRight

![alt text](layout_screenshot/StackLayoutExampleWithTwoMorphCellPositioningBottomRight.png)
```st
|m1 m2 m3|
m1 := Morph new layoutPolicy: StackLayout new; cellPositioning: #bottomRight; yourself.
m2 :=  Morph new color: Color green; extent: (100@100); yourself.
m3 := Morph new color: Color yellow .
m1 addMorph: m2.
m1 addMorph: m3.
m1 openInWorld.
 ```

## Proportionnal layout

This layout allows to modify the relative size of a submorph when the size of the container change.
The goal is to change proportionnaly to the size of the morph.
For doing this, the submorph need a frame where it will be display.
This frame is a percentage of the morph.
For example: if we give a frame of (0 @ 0 corner: 0.5 @ 0.5) to a submorph, it occupies 25% of the morph.
And if we resize the container, the size of the submorph will be resize proportionaly to stay with a occupied frame of 25%.

Exemple 1 : Proportionnal layout with 25% of the morph area.

![alt text](layout_screenshot/ProportionnalLayoutWithLeftTop50perX50perY.png)
```st
|frame sub|
m1 :=SystemWindow new.
m1 layoutPolicy: ProportionalLayout new.
frame := (0 @ 0 corner: 0.5 @ 0.5) asLayoutFrame .
sub := Morph new color: Color red.
m1 addMorph: sub fullFrame: frame.
m1 extent:300@300.
m1 openInWorld.
```
Exemple 2 : Proportionnal layout with 50% of the morph area.

![alt text](layout_screenshot/ProportionnalLayoutWithLeftTop50perY.png)
```st
|frame sub|
m1 :=SystemWindow new.
m1 layoutPolicy: ProportionalLayout new.
frame := (0 @ 0 corner: 1.0 @ 0.5) asLayoutFrame .
sub := Morph new color: Color red.
m1 addMorph: sub fullFrame: frame.
m1 extent:300@300.
m1 openInWorld.
```
Example 3 : Proportionnal layout with 100% of the morph area.

![alt text](layout_screenshot/ProportionnalLayoutExampleWithSystemWIndowWithFulllWindow.png)
```st
|frame sub|
m1 :=SystemWindow new.
m1 layoutPolicy: ProportionalLayout new.
frame := (0 @ 0 corner: 1.0 @ 1.0) asLayoutFrame .
sub := Morph new color: Color red.
m1 addMorph: sub fullFrame: frame.
m1 extent:300@300.
m1 openInWorld.
```
Example 4 : Proportionnal layout with 2 Morph, each Morph was display on 50% of the morph area.

![alt text](layout_screenshot/ProportionnalLayoutExampleWithSystemWIndowWithTwoMorph.png)
```st
|frame sub|
m1 := SystemWindow new.
m1 layoutPolicy: ProportionalLayout new.
frame := (0 @ 0 corner: 1.0 @ 1.0) asLayoutFrame .
sub := Morph new layoutPolicy: TableLayout new.
m3 := Morph new color: Color green; yourself.
m2 := Morph new color: Color red; yourself.
sub addMorph: m2 fullFrame: frame.
sub addMorph: m3 fullFrame: frame.
m1 addMorph: sub fullFrame: frame.
m1 extent: 300@300.
m1 openInWorld.
```

Example 5: Proportional layout with scrollbar
![alt text](layout_screenshot/ProportionnalLayoutWithScrollBar.png)
```st
| window scrollPane pasteUpMorph |
	window := Morph new layoutPolicy: ProportionalLayout new.
	window extent: (500@500).
	scrollPane := ScrollPane new.
	pasteUpMorph := Morph new color: Color yellow .
	pasteUpMorph extent: 1000@1000.
	scrollPane scroller addMorph: pasteUpMorph.
	window addMorph: scrollPane fullFrame: (0@0 corner: 1@1).

	window openInWorld.
```

## Annexe

No minimal size in particular


================================================
FILE: General/MenuBar.md
================================================
# Menubar and World menu

In Pharo, to open tools or execute actions a Menubar (At the top of the screen) and a WorldMenu (Appears on a left click in the world) are present.

This page will document some aspects of those features. 

- [Disable the Menubar/WorldMenu](#disable-the-menubarworldmenu)
- [Add your own entries](#add-your-own-entries)
  * [Add a simple entry](#add-a-simple-entry)
  * [Add a sub menu](#add-a-sub-menu)
- [Change the menu](#change-the-menu)

![MenuBar_Image_WhatIsMenuBarAndWorldMenu.png](./MenuBar_Image_WhatIsMenuBarAndWorldMenu.png)

## Disable the Menubar/WorldMenu

In some case, we want to hide the menubar and/or the world menu. For example, when releasing a new version of a project to deploy, the development tools need to be hidden. 

It is possible to do that with some settings.

**Disable Menubar**

This option is named `Show menubar` in the setting browser and is equivalent of executing:

```Smalltalk
MenubarMorph showMenubar: false
```

**Disable the WorldMenu**

It is not possible to disable this feature alone (without disabling the Menubar) in Pharo <= 7. 

In Pharo 8 it is possible to disable the WorldMenu alone with the setting named `Show world menu` or by executing:

```Smalltalk
PasteUpMorph shouldShowWorldMenu: false
```

**Disable WorldMenu and Menubar**

To disable both the menubar and the world menu it is possible to disable each of them individually, or to change the setting `World menu pragma` to set an empty pragma. Programmatically, it can be done this way:

```Smalltalk
WorldState desktopMenuPragmaKeyword: ''
```

## Add your own entries

It is possible to add entries to the world menu and menu bar.

To build the menu, Pharo uses a pragma mecanism. Each class method containing a pragma `<worldMenu>` will be executed with a menu builder as parameter. The method should then configure the builder to add the needed entries.

### Add a simple entry

To add a simple entry, one need to create and configure a new item in the builder.

Here is a minimal example of a new entry toogling the `Show deprecation warnings` setting:

```Smalltalk
MyClass class>>toggleDeprecationWorldMenuOn: aBuilder
	<worldMenu>
	(aBuilder item: #ToggleDeprecation)
		action: [ Deprecation raiseWarning: (Deprecation raiseWarning) not ]
```

Then multiple things can be configured. 

- `order:` : Takes a number as parameter and sort the entries with those values from the minimal to the maximal value.
- `help:` : Takes a string as parameter and display at is a tooltip on a long mouse over the menu entry.
- `iconName:` : Takes a symbol as parameter and display an icon correspongding to the name next to the menu entry. (See [this page for more infos](CoolSnippets.md#browse-all-available-icons))
- `icon:` : Takes a `Form` as parameter and use it to display next to the menu entry.
- `label:` : Takes a string as parameter and replace the display text of the menu entry from the item name to the string.
- `action:` : Takes a block as parameter and execute it when the entry is clicked.
- `withSeparatorAfter` : Add a separator in the UI after this entry.

```Smalltalk
toggleDeprecationWorldMenuOn: aBuilder
	<worldMenu>
	(aBuilder item: #ToggleDeprecation)
		order: 10;
		help: 'Toggle the show deprecation setting';
		iconName: #tools;
		label: 'Toggle deprecation';
		action: [ Deprecation raiseWarning: (Deprecation raiseWarning) not ];
		withSeparatorAfter
```

### Add a sub menu

It is possible to have submenus in the Menubar. This can be achieve in two ways. 

The first way is to create a new menu and add the children in a `#with:` block.

Example:

```Smalltalk
extensionsWorldMenuOn: aBuilder
	<worldMenu>
	(aBuilder item: #Extensions)
		order: 5;
		iconName: #add;
		with: [ (aBuilder item: #ToggleDeprecation)
				order: 10;
				help: 'Toggle the show deprecation setting';
				iconName: #tools;
				label: 'Toggle deprecation';
				action: [ Deprecation raiseWarning: Deprecation raiseWarning not ];
				withSeparatorAfter ]
```

The second way is to define the submenus in a different place and to use the `#parent:` method to link it to its menu.

Example:

```Smalltalk
extensionsWorldMenuOn: aBuilder
	<worldMenu>
	(aBuilder item: #Extensions)
		order: 5;
		iconName: #add
```

```Smalltalk
toggleDeprecationWorldMenuOn: aBuilder
	<worldMenu>
	(aBuilder item: #ToggleDeprecation)
		parent: #Extensions;
		order: 10;
		help: 'Toggle the show deprecation setting';
		iconName: #tools;
		label: 'Toggle deprecation';
		action: [ Deprecation raiseWarning: Deprecation raiseWarning not ];
		withSeparatorAfter
```

## Change the menu

It is also possible to totally change the Menubar and WorldMenu in case you do not like the current one, or if you want to create a menu for your application. 

In order to do so, you need to define your own pragma to use by executing this code:

```Smalltalk
WorldState desktopMenuPragmaKeyword: 'myOwnMenu'
```

Then you can follow the previous section replacing the `<worldMenu>` pragma by `<myOwnMenu>` in the examples.


================================================
FILE: General/MustKnowForBeginners.md
================================================
# Must know for beginners

This page includes knowledge about thing the Pharo community think important to know as a Pharo beginner.


- [Navigate into the code](#navigate-into-the-code)
  * [Browse, Senders and Implementors](#browse-senders-and-implementors)
  * [Method source with it](#method-source-with-it)
- [Interrupt the Pharo process](#interrupt-the-pharo-process)
- [Debugging facilities](#debugging-facilities)

## Navigate into the code

Pharo offers a lot of ways to navigate into the code, and most of those are used daily by Pharo developers. This section will highlight the most important ones.

### Browse, Senders and Implementors

When reading code we often need to open an entity or to check who is using an entity. To do that, Pharo has different commands:
* **Browse** (`CMD/CTRL + b`): This command will open a new system browser on the class you are currently focusing on
* **Senders/References** (`CMD/CTRL + n`): This command will open a message browser with all the methods calling the method/symbol you are currently focusing on, or, in the case where you are focusing on a class, the references to this class. 
* **Implementors** (`CMD/CTRL + m`):  This command will open a message browser with all the methods whose name is the name of the method/symbol you are currently focusing on, or, in the case where you are focusing on a class, the references to this class like `browse`. 

Alternatively, it is possible to navigate the code using the mouse and the keyboard. In most text editors of Pharo you can use the shortcut `CMD + (Shift +) click` on OSX or `Alt + (Shift +) right click` on Windows/Linux to browse senders, implementors, classes and references. 

Using `CMD + click` on OSX or `Alt + right click` on Windows/Linux allows one to:
- Browse the implementors when you click on a method.
- Browse the class when you click on a class.
- Browse the class or implementors of a method represented by a symbol when you click on a symbol. 

Using `CMD + (Shift +) click` on OSX or `Alt + (Shift +) right click` on Windows/Linux allows one to:
- Browse the senders when you click on a method.
- Browse the references to a class when you click on a class.
- Browse the references to a class or senders of a method represented by a symbol when you click on a symbol. 

> Warning: The click shortcuts on symbols are only working starting from Pharo 9. In the previous version, it will browse the ByteSymbol class. 

### Method source with it

It often happens that we want to see how a feature is done, or we want to edit something but we do not know *where* the implementation is. If we have the name of a menu, for example we can use it to find every location in the image where the name of the menu is written. 

To do that we need to open a playground and type the text (or select some text in an editor) then select on a right click `Code search...` then `Method source with it`.

This will open a message browser with all the methods/class comments containing the string of code we are looking for.

## Interrupt the Pharo process

Pharo currently runs in one native thread. If you launch a method taking a lot of time to run, or if you have an infinite loop in your code, you might want to interrupt the process. 

It is possible to do that in Pharo with the shortcut `CMD/ALT + .`.

> This feature will work in most cases. However, sometimes it might not work, e.g. when faulty code would have taken up too much memory, or when a process is executing outside of the VM (FFI calls).

## Debugging facilities

Pharo includes multiple ways to help with debugging. This section gives some of them.

`Object` implements multiple debugging messages that are useful. They can be sent to any object in your code:

- `#halt` : This method will stop the execution of your code when it is called and will open a debugger. (/!\ Do not use it in a code called multiple times in a fork, or system critical loops or you can regret it by breaking your image. In this case, it is advisable to not save your image in this kind of unstable state)
- `#haltOnce` : This method stops the execution and raises a debugger only on the first time it is called. To enable it once more, use `Menubar -> Debbuging -> Enable all break/inspect once`.
- `#haltIf:` : This method takes a block as a parameter. It will stop the execution and open the debugger if the block as parameter returns `true`.
- `#haltOnCount:` : This method takes a number as an argument, it will stop the execution and open the debugger when it will be called at least the number of times given as argument. Reset the counter via `Menubar -> Debbuging -> Reset Counters`.
- `#inspect` : This message can be called on any object and will open an inspector for the receiver.
- `#inspectOnce` : This message works like #haltOnce for inspecting.

**Example**

``` Smalltalk

myMethod
	
	| temp |
	self doSomething.

	"If you think an infinite loop might happen here, #haltOnCount: might help"
	self haltOnCount: 1000.

	temp := self doSomethingElse.
	
	"Inspect the first value of #temp"	
	temp inspectOnce.

	"Debug only in certain conditions"
	self  haltIf: [ temp isKindOf: ObjectIShouldNotGetHere ].

	1 to: 1000 do: [ :e | 
	
	"I want to stop only one time here to check something."
	self haltOnce.

	self doSomethingWith: e ]

```



================================================
FILE: General/Playground.md
================================================
# Playground

- [Basic usage](#basic-usage)
  * [Do it](#do-it)
  * [Print it](#print-it)
  * [Do it and go](#do-it-and-go)
  * [Inspect it](#inspect-it)
  * [Basic inspect it](#basic-inspect-it)
  * [Debug it](#debug-it)
  * [Profile it](#profile-it)
  * [Code search](#code-search)
- [Some Advices](#some-advices)
  * [Doing vs. Printing](#doing-vs-printing)
- [Advance usage](#advance-usage)
  * [Variables bindings](#variables-bindings)
  * [Remote publishing](#remote-publishing)
  * [Get back previous playground contents](#get-back-previous-playground-contents)
  * [Give a name to a playground to get it back](#give-a-name-to-a-playground-to-get-it-back)
  * [Sharing playgrounds content in multiple local images](#sharing-playgrounds-content-in-multiple-local-images)


Playground is a tool that is most often used for typing Pharo expressions and executing them but it can be used as a scratchpad area where fragments of Pharo code can be entered, stored, edited and evaluated.

You can open Playground with the shortcut `cmd/ctrl + o + w` or using the menu entry from the menubar: 

![open playground from the image](Playground_open_from_image.png)

## Basic usage
The Playground can be used to quickly execute Pharo code. You can write something and then do operations on the code, such as:

### Do it 
Shortcut: `cmd/ctrl + d` It Executes the code/expression

![Do it command on playground](Playground_do_it.png)

### Print it
Shortcut: `cmd/ctrl + p` It Compiles the expression, executes it, sends the message `printString` to the result and displays the resulting string.

![Print it command on playground](Playground_print_it.png)
![Print it result on playground](Playground_print_result.png)

### Do it and go
Shortcut: `cmd/ctrl + g` It executes the code and opens a navigable inspector on the side of the playground. It allows us to browse the object structure.

![Do it and go on the playground](Playground_do_it_and_go.png)

### Inspect it
Shortcut: `cmd/ctrl + i` It executes the code and opens a navigable inspector outside of the playground. It allows us to browse the object structure.

![Inspect on Time now](Playground_inspect_on_Time_now.png)

> The title tells us that `11:55:11.561177 am` is an instance of the class `Time`. The top panel allows us to browse the instance variables of an object and their values. The bottom panel can be used to write expressions to send messages to the object. 

### Basic inspect it
Shortcut: `cmd/ctrl + shift + i` It opens a minimal inspector on the result of the expression. (Might be useful if you work on the Inspector, for example)
### Debug it
Shortcut: `cmd/ctrl + shift + d` It opens a debugger on the code with the context at the start of the snippet.

![Debug it on Time now](Playground_debug_it.png)

>The Debugger is a tool that not only lets you inspect the run-time stack of your program when an error is raised, but it also enables you to interact with all of the objects in your application, including the source code. In many cases you can modify your source code from the debugger and continue executing. The debugger is especially effective as a tool to support test-first development in tandem with SUnit.

### Profile it
Profiles the code with the Pharo profile tool which shows how much time is spent for each message sent.
### Code search
Offers several options provided by System Browser, such as browsing the source code of an expression, searching for senders and implementors, and so on.

You can also use the playground for typing any text that you would like to remember, such as to-do lists or instructions for anyone who will use your image.

![Text on the playground](Playground_with_only_text.png)

## Some Advices
### Doing vs. Printing
The difference between these two actions is visual. try to execute something like `1+5` with `Do it`. Maybe you think that nothing happened because there isn't a visual cue about the execution but in fact, something did happen. You sent the message `+` with argument `5` to the number `1`.

Now try to do it with Print it, the same will happen but you will now see the result printed on the side:

![Print the sum using the playground](Playground_print_sum.png)

That could be useful if you want to understand the result value.

## Advance usage

In this section, we will cover some advanced usages of the Playground. 

![Overview of the Playground](Playground_overview.png)

The previous figure highlights different parts of the playground and we will refer to these in this explanation.

1. The playground name tab
2. The run button
3. The remote publishing button
4. The bindings table
5. The pages history

Out of those, the simplest feature is the run button that will just execute the content of the playground and open an embedded inspector in the playground with the result of the expression. It is the equivalent of `Do it and go` (cmd/ctrl + g).

### Variables bindings

The playground is able to manage variables in two ways. The first way is the classic Smalltalk way of declaring temporary variables (`| varName |`) at the beginning of the playground and using them later. 

Example:

```Smalltalk
| result |
result := 1 + 2.
result := result + 3.
```

Using these kind of variables will work as temporary variables of methods. During the execution they will be initialized with nil. They will be used during the current execution and then they will be discarded. 

> Note: If you select a piece of code to execute, do not forget to select the temporary variables declaration line.

The second way to manage variables in the playground is to use them without declaring them. 

Example:

```Smalltalk
result := 1 + 2.
result := result + 3
```

By doing so, during its first use, the playground creates and initializes the new variable to nil, then stores it. This means that the variable will still exist and will still contain its value after the execution. If you execute the previous piece of code in a playground and then select `result` to inspect it, you will find the value `6`.

This feature is useful while playing with some code. For example, if you need to work on a model, instead of recreating the model at each run you can just initialize it one time and reuse the variable containing the model for the entire playground session.

If at some point you don't remember the content of some variables, you can find all the variables bound to the playground in the binding table button (4 on the previous overview screenshot). This table also allows you to unbind variables by clicking on the cross next to their name.

### Remote publishing

In case you want to share some code with someone, the Playground includes a remote publishing service. 

By clicking the button 3 from the overview screenshot previously displayed, you will publish the content of your playground on the cloud and get a link to it. 

You can then share this link and everyone with it will be able to see the content of your playground.

### Get back previous playground contents

Whilst working, the playground will occasionally save the code in a local file. Using those saved files you have the ability to open a new playground containing the code of a previously closed playground. 

In order to get a previous playground back, you need to open a new playground and use button 5 from the overview, the *page history button*. You will see the start of the code from your previous playgrounds and you need to double click on the one you want to get it back.

### Give a name to a playground to get it back

Another feature of the playground is the ability to give a name to a playground in order to get its content back easily once closed.

In order to name a playground, you need to double click the page name (1 on the overview screenshot) and type the name of your choice. Once this is done, the playground will save this name locally. 

If you close the playground and want to get it back, you can open a `Spotter` (`shift + enter`) and type the name of the closed playground. In the list of results of the spotter, you should find a section named `Playground named pages` containing the name of your playground. By selecting this entry, a new playground with the code of your named playground will open.

### Sharing playgrounds content in multiple local images

One last feature to highlight is the ability to share playground code between multiple local Pharo images.

We have seen in the previous sections that it is possible to get back the content of the previous playgrounds via the `page history button` and the ability of the Spotter to find named playground pages. By updating some settings of the playground, it is possible to share that history through all your images.

As explained before, when using the playground and naming playgrounds, the content is stored in local files. In order to share the playgrounds through different images, they need to use the same folders to store their content. Two settings are available for that and can be found in the setting browser under `Tools` -> `Glamourous Toolkit`. 

![Settings around the playground](Playground_settings.png)

The two interesting settings are:

- `Local Playground cache directory`: this setting allows one to choose a specific folder to store the unnamed playground contents.
- `Local Playground stash directory`: this setting allows one to choose a specific folder to store the named playground contents.

Sharing this setting with multiple images will allow one to share playground history across all those images.


================================================
FILE: General/Pragmas.md
================================================
# Pragmas

- [Description](#description)
- [How to declare a new pragma](#how-to-declare-a-new-pragma)
- [Collect pragmas](#collect-pragmas)
  * [Find pragmas in the IDE](#find-pragmas-in-the-ide)
  * [Get the pragmas of a CompiledMethod](#get-the-pragmas-of-a-compiledmethod)
  * [Collect pragmas in a hierarchy](#collect-pragmas-in-a-hierarchy)
  * [Collect pragmas in the image](#collect-pragmas-in-the-image)
- [Act on collected pragmas](#act-on-collected-pragmas)
- [Examples of pragma usage](#examples-of-pragma-usage)
  * [Pragmas used in the IDE](#pragmas-used-in-the-ide)
- [See also](#see-also)

## Description

Pragmas in Pharo are annotations on `CompiledMethods`. They are used to attach additional properties to the methods to make those methods easily collectable through reflectivity and to ease the creation of special handlings.

Pragmas are part of Pharo's syntax and are declared like this: `<aPragma>`. They should be placed at the beginning of a method, after the method selector.

This documentation illustrates the use of pragmas by describing how to use them to annotate an application's parameters and generate documentation from those parameters comments.

## How to declare a new pragma

To declare a new pragma, you only need to add it to, at least, one method in the system.

For example, annotating an application parameter can be done as follow:

```Smalltalk
isInAdminMode
  "If this parameter is true, the application will allow one to access all the administration panels."
  
  <applicationParameter>
  ^ isAdminMode
```

Pragmas can take literals as a parameter in order to configure their future handling.

In our example, we might want to declare which parameters are optional.

```Smalltalk
isInAdminMode
  "If this parameter is true, the application will allow the user to access all the administration panels."
  
  <applicationParameterOptional: false>
  ^ isAdminMode
```

## Collect pragmas

Once defined, we need to be able to collect the pragmas either to modify them during the development or to use them to handle a feature of the application.

We will explore these possibilities in the following sections.

### Find pragmas in the IDE

During the development of the application, the developer might need to browse the currents senders of a pragma. This can be done in the same way we browse method selectors in Pharo.

You can:
- Select a symbol is the name of the pragma and type `CMD + n` (or `CTRL + n` depending on your operating system).
- Select a symbol which is the name of the pragma and right click on it then select `Browse senders` in the search menu.
- Type the name of the pragma in the Spotter (`SHIFT + ENTER` to open Spotter) followed by `#p`.
- Use the `Finder` (accessible via the menu through path: `Menubar -> Tools -> Finder`) and select the `Pragmas` mode.
- Send the message `senders` to a symbol which is the name of the pragma.

### Get the pragmas of a CompiledMethod

If you have a compile method you can directly ask it his pragmas via the `#pragmas` method.

For example, you can get all methods with a pragma like this:

```Smalltalk
SystemNavigation new browseAllSelect: [ :method | method pragmas isNotEmpty]
```

### Collect pragmas in a hierarchy

When you want to use the pragmas in your application you have two ways to collect them. If you want to find the pragmas in one class or one hierarchy of class, you can use the `Pragma` class to collect them.

The Pragma class implements different ways to get to pragmas depending on your requirements.

You can use:
- `allNamed: aSymbol from: aSubClass to: aSuperClass`
- `allNamed: aSymbol from: aSubClass to: aSuperClass sortedByArgument: anInteger`
- `allNamed: aSymbol in: aClass`
- `allNamed: aSymbol in: aClass sortedByArgument: anInteger`
...

In our example, we might want to use this way of accessing our pragmas if all parameters are defined in a configuration object.

In that case, we can access them this way:

```Smalltalk
Pragma allNamed: #applicationParameterOptional: in: MyConfiguration
```

Or if we have a hierarchy of configurations:

```Smalltalk
Pragma allNamed: #applicationParameterOptional: from: MyConfiguration to: MyAbstractConfiguration
```

### Collect pragmas in the image

You can also use the Pragma class to collect pramgas in the entire image by using:
- `allNamed: aSymbol `
  
A second, now less reccomended way to collect pragmas, is to use the PragmaCollector. This class can be configured with a query and will return all the pragmas matching the query.

To configure the PragmaCollector we need to send implement a filter block. If we want to collect the `primitive:` pragmas:

```Smalltalk
PragmaCollector filter: [:prg | prg selector = #'primitive:' ]
```

Once configured we can execute the collection of the pragmas by sending the method #reset to the pragma collector:

```Smalltalk
(PragmaCollector filter: [:prg | prg selector = #'primitive:' ]) reset
```

Then you can iterate on the result using `#do:`, `#collect:`, `#reject:`, etc or use them directly through `#collected`. 

In our example we might want to access them this way:

```Smalltalk
(PragmaCollector filter: [:prg | prg selector = #'applicationParameterOptional:' ]) reset collected
```

Or we can select only non optional parameters this way:

```Smalltalk
(PragmaCollector filter: [:prg | prg selector = #'applicationParameterOptional:' and: [ (prg argumentAt: 1) not ] ]) reset collected
```

## Act on collected pragmas

Once collected, we need use the pragmas to implement the feature we want.

For that, the pragmas can answer diverse messages to get their context. For example, they can answer to:
- `#method` : Returns the CompiledMethod in which the pragmas is.
- `#arguments` : Returns the arguments of the pragmas.
- `#argumentAt:` : Returns the value of the n-th argument of the pragma instance.
- `#argumentNamed:`: Returns the value of the arguemnts following a subpart of the pragma selector. This is available since Pharo 8.
- `#selector` : Returns the pragma selector.
- `#methodClass` : Returns the class in which the method containing the pragma is.

With that information, we can then build our handler.

The next snippet will collect the senders of our example pragma and generate user documentation about them:

```Smalltalk
String
    streamContents: [ :stream | 
        stream
            << 'Documentation';
            lf;
            lf.
        (PragmaCollector filter: [ :prg | prg selector = 'applicationParameterOptional:' ]) reset
            do: [ :pragma | 
                stream
                    << '- ';
                    << pragma methodSelector.
                (pragma argumentAt: 1) ifTrue: [ stream << ' (Optional)' ].
                stream
                    << ': ';
                    << pragma method comment;
                    lf ] ]
```

Here is an example on how to use `#argumentNamed:`:

```Smalltalk
(PragmaCollector filter: [:prg | prg selector = #'loaderNamed:priority:' and: [ (prg argumentNamed: #priority) > 0 ] ]) reset collected
```

## Examples of pragma usage

Pragmas are used for many things in Pharo and you can find examples of their usage by browsing Pharo code using them.

For example, the setting framework is built with pragmas. The pragma `<systemSetting>` is used to register new settings the setting browser.

And other examples can be found in the world menu registration and is explain if the page [Menubar and World menu](MenuBar.md).

### Pragmas used in the IDE

Some pragmas are interesting to know in Pharo IDE. You can find information on them on [this page](InterestingsToKnowForBeginners.md#useful-pragmas)

## See also

- [Pragmas: Literal Messages as Powerful Method Annotations](https://rmod-files.lille.inria.fr/Team/Texts/Papers/Duca16a-Pragmas-IWST.pdf)


================================================
FILE: General/Profiling.md
================================================
# Profiling
Profiling a program is the act of measuring, for example, the time or space it takes to execute.

- [Time Profiling](#time-profiling)
  * [Programmatically open a Time Profiler](#programmatically-open-a-time-profiler)
  * [Utility methods on blocks to profile](#utility-methods-on-blocks-to-profile)
  * [Interactively open a Time Profiler](#interactively-open-a-time-profiler)
- [Space Profiling](#space-profiling)

## Time Profiling
### Programmatically open a Time Profiler
If `SimpleGridExample new open` is the program you want to profile, run:
```Smalltalk
TimeProfiler spyOn: [ SimpleGridExample new open ]
```
Result: a breakdown of the methods in which the program spent time.

![image](Profiling_Image_TimeProfilerFromCommandLine.png)

> If your block execution time is too fast (~ < 3ms), the time profiler will not display any result.

The time profiler UI is composed of multiple parts:
- *Tallies tree* displays a tree of all the nested method calls of the execution with the percentage of time spent in each call. The tree stops at primitive calls or calls that are too fast to be benchmarked (~ < 3ms)
- *Code* displays the code of the selected method in the `tallies tree`
- *Statistics* displays memory and garbage collection statistics. Those informations may be useful if too much execution time is spent in the full or incremental garbage collection. This may signal that the code executed create too many temporary objects. The code can then be reviewed to create less copies or temporary objects. If it is not possible, consider changing the parameter of the VM to do less garbage collection during the execution of some algorithms.
- *Full report* displays textual informations such as the tallies tree and statistics, but also informations on leaf methods where most of the time is spent. (Section `**Leaves**`) This can be a good source of information to find bottlenecks where the time is spent.

### Utility methods on blocks to profile
If `SimpleGridExample new open` is the program you want to profile, **inspect** or **print**:

```Smalltalk
[ SimpleGridExample new open ] bench.
```

Result: the number of times the profiler was able to run the program per second.

![image](Profiling_Image_Bench.png)

You can also check the execution time of a set of instructions by inspecting or printing the result of the `timeToRun` method on blocks like this:

```Smalltalk
[ SimpleGridExample new open ] timeToRun
```

### Interactively open a Time Profiler
You can access a UI for the time profiler tool via the menu bar.

![image](Profiling_Image_TimeProfilerMenuItem.png)

Result: type your code in the top box and click "Profile it".

![image](Profiling_Image_TimeProfilerToolUI.png)

## Space Profiling
Imagine you want to know how much instances of the classes Point and TextMorph there are in the system, and how much space they occupy. **Inspect**:
```Smalltalk
((SpaceTally new spaceTally: (Array with: TextMorph with: Point)) 
	asSortedCollection: [:a :b | a spaceForInstances > b spaceForInstances])
```
Result:

![image](Profiling_Image_SpaceTally.png)


================================================
FILE: General/ProgressBar.md
================================================
# Progress bar

This document covers different ways to display a progress bar during code execution.

## Progress bar on iterators

The easiest way to create a progress bar is to use the method `do:displayingProgress:`. This method is available on Collections and adds a progress bar automatically updated during iterations.

```Smalltalk
(1 to: 100) do: [ :each | each logCr. 100 milliSecond wait. ] displayingProgress:  [ :each | 'Iterating step ' , each asString ]
```

Refresh time can also be customized if better performances are needed. For example, the following code will update the progress bar every 2 seconds:

```Smalltalk
(1 to: 100) do: [ :each | each logCr. 100 milliSecond wait. ] displayingProgress:  [ :each | 'Iterating step ' , each asString ] every: 2000
```

## Use Jobs

An other way to display a progress bar is to use Jobs.

```Smalltalk
[:job | job title: 'Let us get started'.
	1 to: 10 do: [:each |
		job
			progress: (0.1 * each);
			title: 'Youpi ', each printString.
		(Delay forMilliseconds: 100) wait.
		] ]  asJob run
```

Or using UIManager:

```Smalltalk
UIManager default
	displayProgress: 'Let us get started'
	from: 1
	to: 10
	during: [ :bar | 
		1 to: 10 do: [:each |
			bar
				value: each;
				title: 'Youpi ', each printString.
	  (Delay forMilliseconds: 100) wait.
	]  ]
```

Be careful while using this method. It might cause performance issues when time between two steps is short.

However, the following code shows a way to avoid these issues.

```Smalltalk
UIManager default
	displayProgress: 'Let us get started'
	from: 1
	to: 40
	during: [ :bar | | lastUpdate | 
		lastUpdate := 0.
		1 to: 40 do: [:each |
			((Time millisecondsSince: lastUpdate) >= 500) ifTrue: [ 
				bar
					value: each;
					title: 'Youpi ', each printString.
				lastUpdate := Time millisecondClockValue
				 ].
	  (Delay forMilliseconds: 100) wait.
	]  ]
```

The trick is to leave at least 500 milliseconds between two updates instead of updating the bar each time we call `value:` or `title:`.


================================================
FILE: General/Refactorings.md
================================================
# Refactoring in Pharo 8.0

## Introduction

Pharo offers many automatic refactoring tools. This tutorial presents what refactorings are, when and how to apply them and to show any possible inconvenience before using them.

## What is refactoring?

Martin Fowler defines refactoring as: "... It is a disciplined technique to restructure an existing body of code, altering its internal structure without changing its external behavior" [1](#references). This means that before carrying out any type of refactoring in the code it is important to have complete test coverage to demonstrate that the code behavior does not change during the refactoring process.

## The most popular refactorings supported by Pharo 8.0

| Refactoring | Supported in |
| ---------- | ---------- |
| [Rename](#rename)   | Package, Class, Method, Instance and Temporary Variable |
| [Extract](#extract)   | Method and Temporary Variable  |
| [Remove](#remove)| Package, Class, Method and Instance Variable |
| [Copy](#copy) | Class |
| [Move](#move) | Class and method |
| [Inline](#inline) | Method and Temporary Variable |
| [Push up / Push down](#push-up-and-push-down) | Method and Instance Variable |
| [Replace](#replace) | Method |
| [Other refactorings](#other-refactorings) |  Class, Method, Instance and Temporary Variable |

# Rename

Renaming seems like a trivial refactoring however it can lead to many complications because this action can lead to involuntary changes of elements not related to the same name. The Pharo's rename tool has can minimize these errors.

## When should we rename?

1. When the name is not descriptive enough.
2. The name of the class / method / variable does not match what it really is.
3. Something new was introduced that requires the existing code to have a new more specific name.
 
> This refactoring can be done for classes, methods and variables.
>
>1. Select the `class / variable / method `.
>2. Press **Meta+R** or from the menu, select **Rename**.
>3. Fill the input of dialog with the new name and press **Ok** button.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/tHdt11WDq2o/0.jpg)](http://www.youtube.com/watch?v=tHdt11WDq2o)

# Extract

The extraction Pharo's tools allow developers to reshape their code when they have duplicate code or when they want to change the design.

Pharo can perform this refactoring to extract methods and extract temporal variables.

## Extract temporary variable

#### Before
``` Smalltalk
Example >> method
    | a b c|
    a := 1.
    b := a + list size.
    c := b + list size.
```
#### After
Selecting `list size` on source code
``` Smalltalk
Example >> method
    | a b c d|
    a := 1.
    d := list size.
    b := a + d.
    c := b + d.
```

>1. Select the section of `source code` you want to convert in temporary variable.
>2. Press **Meta+T** or from the menu, select **Source code**.
>3. Select **Extract temp** option.
>4. Fill dialog's input with the name of the variable and press **Ok** button.

## Extract method

#### Before
``` Smalltalk
Example >> method
    | a b c d|
    a := 1.
    b := 2.
    c := a + b.
    d := a + c.
```
#### After
Selecting `a + b` on source code
``` Smalltalk
Example >> method
    | a b c d|
    a := 1.
    b := 2.
    c := self add: a to: b.
    d := self add: a to: c.

Example >> add: a to: b
    ^ a + b
```

>1. Select the section of the `source code` you wish to extract.
>2. Press **Meta+T** or from the menu, select **Source code**.
>3. Select **Extract method** option.
>4. Fill the input of dialog with the name of method and press **Ok** button.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/LfyN3bo4b0A/0.jpg)](http://www.youtube.com/watch?v=LfyN3bo4b0A)

# Remove

Sometimes when the code is refactored it can end with code that is no longer used, or that should no longer be used. Therefore, it is necessary to eliminate all the unused code since this affects the developers who work and try to understand the source code.

>This refactoring can be done for packages, classes, methods and variables.
>
>1. Select the `package / class / variable / method`.
>2. Press **Meta+X**

# Copy

Many times we want to change or add some functionalities to our code, however this entails major changes which makes it dangerous to do it on the original class. That is why it may be necessary to copy the classes to have a backup in case you want to reverse the changes.

>Currently this tool only applies to classes and to use it you just have to follow the following steps:
>
>1. Select `class`.
>2. Press **Meta+C** or from the menu, select **Copy**.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/wgeVyFltKXY/0.jpg)](http://www.youtube.com/watch?v=wgeVyFltKXY)

# Move

Move allows you to move classes and methods from one package to another, and move methods to class / instance side or even move them to another class.

## Move to package

> ### Class
>
>1. Select `class or classes` that you want to move.
>2. Press **Meta+MC** or from the menu, select **Refactorings** and then select **Move to package** option.
>3. Select the package and press **Ok** button

> ### Method
>
>1. Select the `method or methods` to be moved.
>2. Select **Refactorings** and then select **Move to package** option.
>3. Select the package and press **Ok** button.

## Move to class

>1. Select the `method or methods` to be moved.
>2. Select **Refactorings** and then select **Move to another class** option.
>3. Select the new class for method(s) and press **Ok** button.

## Move to class side

>1. Select the method or methods to be moved.
>2. Press **Meta+TC**, select **Refactorings** and then select **Move to class side** option.

## Move to instance side

>1. Select the `method or methods` to be moved.
>2. Press **Meta+TI**, select **Refactorings** and then select **Move to instance side** option.

# Inline

Inline refactoring allows you to reverse extract refactoring of a method or temporary variable.

## Inline temp

Inline variables replaces the use of redundant variables with its initializer.

#### Before
``` Smalltalk
Example >> method
    | number b |
    number := anotherClass value.
    b := 3 + number.
```
#### After
Selecting `number` temp on source code
``` Smalltalk
Example >> method
    | b |
    b := 3 + anotherClass value.
```

>1. Select the `temporary variable` in the source code.
>2. Press **Meta+T** or from the menu, select **Source code**.
>3. Select **Inline temp** option.

## Inline method

The results of inline method place methods's body in the body of the method where we select its call.

#### Before
``` Smalltalk
Example >> method
    | a b c d|
    a := 1.
    b := 2.
    c := self add: a to: b.
    d := self add: a to: c.
    
Example >> add: a to: b
    ^ a + b
```
#### After
Selecting `self add: a to: b.` on source code
``` Smalltalk
Example >> method
    | a b c d|
    a := 1.
    b := 2.
    c := a + b.
    d := a + c.
```

>1. Select the `call to method` in the source code.
>2. Press **Meta+T** or from the menu, select** Source code**.
>3. Select **Inline method** option.

## Inline senders

This refactoring replaces all calls to the method selected from its class by the body of its implementation, in addition to the method itself being eliminated.

>1. Select the `method`.
>2. From the menu, select **Refactorings**.
>3. Select **Inline senders** option.

# Push up and Push down

## Push up method

Gets rid of duplicate code. If you need to make changes to a method, it’s better to do so in a single place than have to search for all duplicates of the method in subclasses; this refactoring technique can also be used if, for some reason, a subclass redefines a superclass method but performs what’s essentially the same work.

>1. Select the method
>2. Select **Meta+PU** or from the menu, select **Refactorings** and then select **Push up** option.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/nZiLNx4Y6tA/0.jpg)](http://www.youtube.com/watch?v=nZiLNx4Y6tA)

## Push down method

Improves class coherence. A method is located where you expect to see it. For example if you see that a method is needed by more than one subclass, but not all of them, it may be useful to create an intermediate subclass and move the method to it. This allows avoiding the code duplication that would result from pushing a method down to all subclasses.

>1. Select the method
>2. Select **Meta+PD** or from the menu, select **Refactorings** and then select **Push down** option.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/F_JjZfZzCqY/0.jpg)](http://www.youtube.com/watch?v=F_JjZfZzCqY)

In the same way as in the methods you can perform the push up and push down refactorings on the instance variables

## Push up variable

>1. Select the `variable`.
>2. From the menu select **Push up** option.

## Push down variable

>1. Select the `variable`.
>2. From the menu select **Push down** option.

# Replace

## Replace senders

Replace senders helps us to change the senders of the selected method to the name of another method that we want, considering that the method with which we replace it must have the same number of arguments as the original.

>1. Select the `method`.
>2. From the menu, select **Refactorings**.
>3. Select **Replace senders** option.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/CJjZYugsqZg/0.jpg)](http://www.youtube.com/watch?v=CJjZYugsqZg)

## Find and Replace method

Find and replace helps us when we have duplicate code, if this refactoring consists in selecting a method and looking for the occurrences of your body in a range of methods that is selected.

#### Before
``` Smalltalk
Example >> textInputOn: html withName: aString andSymbol: aSymbol
    html text: aString.
    html textInput on: aSymbol of: self contact.
    html break

Example >> renderContentOn: html
    html
	form: [ html text: 'Name:'.
  	    html textInput on: #name of: self contact.
	    html break.
	    html text: 'Email address:'.
	    html textInput on: #emailAddress of: self contact.
	    html break.
	    html text: 'Example:'.
	    html textInput on: #example of: self contact.
	    html break]
```
#### After
``` Smalltalk
Example >> textInputOn: html withName: aString andSymbol: aSymbol
    html text: aString.
    html textInput on: aSymbol of: self contact.
    html break

Example >> renderContentOn: html
    html
	form: [ self textInputOn: html withName: 'Name:' andSymbol: #name.
   	    self textInputextInputOnt: html withName: 'Email address:' andSymbol: #emailAddress.
	    self textInputOn: html withName: 'Example:' andSymbol: #example ]
```

>1. Select the `method`.
>2. From the menu, select **Refactorings**.
>3. Select **Find and replace** option.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/yxOn3tdh1wU/0.jpg)](http://www.youtube.com/watch?v=yxOn3tdh1wU)

# Other refactorings

## Generate accessors

This refactoring generates the get and set messages of the instance variables, can be used from the class and the variables.

#### Before
``` Smalltalk
Object subclass: #Example
    instanceVariableNames: 'a'
    classVariableNames: ''
    package: 'Refactoring-Example'
```
#### After
``` Smalltalk
Object subclass: #Example
    instanceVariableNames: 'a'
    classVariableNames: ''
    package: 'Refactoring-Example'
    
Example >> a
    ^ a

Example >> a: anObject
    a := anObject
```

>### Class
>
>1. Select the `class` that you want generate accessors.
>2. Select **Meta+GA** or from the menu, select **Generate accessors** option.

>### Variables
>
>1. Select the `variable(s)` that you want generate accessors.
>2. From the menu, select **Generate accessors** option.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/LMnv8HDNE-4/0.jpg)](http://www.youtube.com/watch?v=LMnv8HDNE-4)

## New subclass

Generate a new subclass of a class. 

#### Before
``` Smalltalk
Object subclass: #MyA
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'

MyA subclass: #MyB
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'</pre>
```
#### After
Selecting the `MyA` class
``` Smalltalk
Object subclass: #MyA
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
    
MyA subclass: #MyB
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
    
MyA subclass: #MyC
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
```

>1. Select `class`.
>2. From the menu, select **Refactorings** and then select **New subclass** option.
>3. Fill the dialog's input with new class's name.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/PLqO6s46p_o/0.jpg)](http://www.youtube.com/watch?v=PLqO6s46p_o)

## Insert subclass

Generate a new subclass of a class between the class and its subclasses. This refactoring is useful when we have to specialize some classes.

#### Before
``` Smalltalk
Object subclass: #MyA
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'

MyA subclass: #MyB
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
```
#### After
Selecting the `MyA` class
``` Smalltalk
Object subclass: #MyA
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
    
MyA subclass: #MyC
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
    
MyC subclass: #MyB
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
```

>1. Select `class`.
>2. From the menu, select **Refactorings** and then select **Insert subclass** option.
>3. Fill the dialog's input with new class's name.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/vflwFbwY58A/0.jpg)](http://www.youtube.com/watch?v=vflwFbwY58A)

## Insert superclass

Generate a new superclass of a class between the class and its superclass. This refactoring is useful when we must generalize to avoid the redundancy of the classes.

#### Before
``` Smalltalk
Object subclass: #MyA
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'

MyA subclass: #MyB
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
```
#### After
Selecting the `MyB` class
``` Smalltalk
Object subclass: #MyA
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
    
MyA subclass: #MyC
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
    
MyC subclass: #MyB
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'Refactoring-Example'
```

>1. Select `class`.
>2. From the menu, select **Refactorings** and then select **Insert subclass** option.
>3. Fill the dialog's input with new class's name.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/b1wpkuxYwHc/0.jpg)](http://www.youtube.com/watch?v=b1wpkuxYwHc)

## Jump to test class

This seems trivial, however this command offers us a shortcut to automatically create a class for our tests or go to tests class.

>1. Select `class`.
>2. Press **Meta+GJ** or from the menu, select **Jump to test class**.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/IC6MawvjzwE/0.jpg)](http://www.youtube.com/watch?v=IC6MawvjzwE)


##  Abstract instance variables

This refactoring generate accessors methods if they don't exist and replace every direct access to class variables with accessor methods.

#### Before
``` Smalltalk
Object subclass: #MyA
    instanceVariableNames: 'a'
    classVariableNames: ''
    package: 'Refactoring-Example'

MyA >> method
    |result|
    a := self initializeVariable.
    result := a value.
```
#### After
Selecting the `a` variable
``` Smalltalk
Object subclass: #MyA
    instanceVariableNames: 'a'
    classVariableNames: ''
    package: 'Refactoring-Example'
    
Example >> a
    ^ a

Example >> a: anObject
    a := anObject

MyA >> method
    |result|
    self a: self initializeVariable.
    result := self a value.
```

>1. Select `variable`.
>2. From the menu, select **Abstract instance variables** option.

[![Pharo - Rename refactoring](https://img.youtube.com/vi/cRBICE66v7g/0.jpg)](http://www.youtube.com/watch?v=cRBICE66v7g)

# References
[1] Martin Fowler, [Refactoring - Improving the Design of Existing Code](https://refactoring.com/)


================================================
FILE: General/SessionsManagement.md
================================================
# Sessions Management

 * [Description](#description)
 * [Quick start](#quick-start)
 * [Register a class to the session manager](#register-a-class-to-the-session-manager)
 * [Start-up, Shut-down and Saving actions](#start-up--shut-down-and-saving-actions)
 * [Checking the start-up and shut-down list](#checking-the-start-up-and-shut-down-list)

## Description

Pharo images have a concept of **Session**. On each image startup the current session is invalidated and a new session is created. A session starts when one open a Pharo image and stop when one close it. A session is also invalidated when saving the image, therefore creating a new session.
It is possible to hook your project to those sessions to perform actions such as executing code at startup, shutdown, image saving...

## Quick start

Here is a quick start to show how to set a class variable to the home folder of a user at startup and removing this value at shut down. 

You need to do those actions in a `#startUp:` method and `#shutDown:` method on the class side of your class. 

```Smalltalk
MyClass class>>startUp: isImageStarting
	isImageStarting
		ifTrue: [ MyVariable := FileLocator home asFileReference ]
```

```Smalltalk
MyClass class>>shutDown: isImageQuitting
	isImageQuitting
		ifTrue: [ MyVarible := nil ]
```

Then you need to register the class in the `SessionManager` of Pharo. This is usually done in the `#initialize` method (class-side).

```Smalltalk
MyClass class>>initialize
	SessionManager default registerUserClassNamed: self name.
	self startUp: true. "Here we execute it to set up the value while loading the project."
```

## Register a class to the session manager

It is possible to register classes to the `SessionManager` of Pharo in order to be able to execute code at start-up, shut-down or when we save a Pharo image.

The simplest way to do that is to add this in the class initialization method of the class you want to register.

```Smalltalk
MyClass class>>initialize
	SessionManager default registerUserClassNamed: self name
```
  
Sometimes, the order of execution of start-up/shut-down actions might matter. To manage this, it is possible to set a priority.
  
```Smalltalk
MyClass class>>initialize
	SessionManager default registerUserClassNamed: self name atPriority: 60
```
Registered handlers with lower priority will be executed first.
The actions registered using `#registerUserClassNamed:[atPriority:]` will have a low priority in the startup/shutdown list.
It is possible to further refine the priorities using categories. 

The SessionManager has categories. `User` category is one of them. Categories have priority between each others.
By default the system comes with those categories (sorted by priority from the highest to the lowest one):

- System (`#registerSystemClassNamed:[atPriority:]`): manages system related modules such as FFI, Files, OSEnvironment, ...
- Network (`#registerNetworkClassNamed:[atPriority:]`): manages network related modules such as Zinc or git.
- Graphical User Interface (`#registerUserGUINamed:[atPriority:]`): manages GUI related modules such as events, sensors, morphic, ...
- Tools (`#registerToolClassNamed:[atPriority:]`): manages the tools of Pharo IDE such as Code browser, Spotter, Inspector, ...
- User (`#registerUserClassNamed:[atPriority:]`): for the users to register their projects most of the time.

> Most of the time, users should use the `User` category. Use the other ones only if you know what you are doing.

It is possible to create a new category:

```Smalltalk
SessionManager default createCategory: aCategoryName.
SessionManager default createCategory: aCategoryName after: anotherCategoryName.
```

> It is not recommanded to register a new category before the System, Network or GUI ones. If you do, be sure of what you are doing.

Then one can register classes in you new custom category:

```Smalltalk
SessionManager default register: (ClassSessionHandler forClassNamed: self name) inCategory: (SessionManager default categoryNamed: 'MyCategory').
SessionManager default register: (ClassSessionHandler forClassNamed: self name) inCategory: (SessionManager default categoryNamed: 'MyCategory') atPriority: 30.
```

## Start-up, Shut-down and Saving actions

Once a class is registered in the `SessionManager`, it is possible to add start-up and shut-down actions that will be executed when we open, close or save an image.

To register a start-up action, you need to implement a #startUp: method in the class side of your registered class.
This method is called in two situations: when you launch an image and after you save an image.
This method takes a boolean as parameter. The value of this parameter is true when we start the image and false when we save it. 

Example:

```Smalltalk
MyClass class>>startUp: isImageStarting
	Transcript traceCr:
		(isImageStarting
			ifTrue: [ 'Image is starting' ]
			ifFalse: [ 'Image was saved' ])
```

To register a shut-down action, you need to implement a #shutDown: method in the class side of your registered class.
This method is called in two situations: when you quit an image and when you save an image.
This method takes a boolean as parameter. The value of this parameter is true when we quit the image and false when we only save it. 

Example:

```Smalltalk
MyClass class>>shutDown: isImageQuitting
	Transcript traceCr:
		(isImageQuitting
			ifTrue: [ 'Image is quitting' ]
			ifFalse: [ 'Image is been saved' ])
```


## Checking the start-up and shut-down list

When manipulating sessions, it is sometime interesting to check the current start-up and shut-down lists.

It is possible to do this this way:

```Smalltalk
SessionManager default startupList.
SessionManager default shutdownList.
```

The results of those methods will be sorted by priority.


================================================
FILE: General/SettingUpANewProject.md
================================================
# Setting up a new project

In this article, we describe the good workflow for setting up a new project in Pharo. We will guide you through the whole process from getting a new Pharo image, creating the GitHub repository, and setting up the CI.

We will demonstrate everything by setting up a toy project - `Counter`, inspired by Chapter 14. Seaside by Example of [Pharo by Example](https://files.pharo.org/books-pdfs/updated-pharo-by-example/2017-01-14-UpdatedPharoByExample.pdf) book. It is a simple class that has a value which can be incremented or decremented.

## Step 0. Download and install Pharo Launcher

In order to work with Pharo, you should dowload and install Pharo Launcher - a tool for managing Pharo images. It is available for Windows, Linux, and macOS in both 32bit and 64bit version and can be dowloaded from [http://pharo.org/download]().

![](SettingUp_DownloadPharo.png)

## Step 1. Get a fresh Pharo image

Instructions in this tutorial were written for Pharo 8, 64bit. But they should also work fine for Pharo 7. We suggest that you start your new project with the latest development version of Pharo.

Open your Pharo Launcher. You will see two panels:

- **New Image Templates** on the left - here you can select a template of a new image that you want to create on your machine.
- **Current Images** on the right - created images will appear here. By double-clicking on image name, you can launch it.

Open the list of `Official distributions` in the left panel and double-click on the latest development version of Pharo. In our case, this is `Pharo 8.0 - 64bit (development version, latest)`. Give a nice descriptive name to your new image and press `OK`. You can now find your image in the right panel. Launch it by double-clicking on the image name.

![](SettingUp_PharoLauncher.png)

## Step 2. Create a package and a class

!! ( In Pharo 13 or more latest version, we have "**slots: { #variable }**" instead of "**instanceVariableNames: 'variable'**" )

Let us make our first package. In your newly made image in Pharo Launcher, in the top menu bar choose *Tools* then *System Browser*.

![System Browser tool for developing projects in Pharo](SettingUp_SystemBrowser.png)

System Browser is the main tool to develop a project in Pharo. It allows browsing packages, classes, protocols and methods. The most left panel shows all the packages that already exist. To create a new one, press the right click of a mouse on this part, and choose the option New Package. 

![Pharo System Browser, new package creation pop-up menu](SettingUp_NewPackage.png)

Choosing it, a new small window will open, where you give a name to the package you are creating. Type the name *Counter* and press ok.


To create a class, first you need to choose the package in which it will be located. Then look at the bottom part of the System Browser in it there is a template for creating a class. It gives us all the information we need: superclass, variables, package. Creating a new class is as easy as filling out this template. Continuing with our example, we will create a new class *MyCounter*. The superclass is *Object*, so we will not change that. But we will change the name of the class. You will notice that saving our class, the second left part of SystemBrowser is no longer empty.

![Pharo System Browser, new class created](SettingUp_AddingClass.png)

## Step 3. Write some failing tests

If we want to follow the [TDD (test driven development)](https://fr.wikipedia.org/wiki/Test_driven_development), we first need to create tests. All tests are stored in a test class, which is a subclass of *TestCase*. This class can be generated by doing a right-click on the class name and selecting *Jump to test class*. This option will generate a test class in a new package *Counter-Tests*.

![Pharo System Browser, new Test class created](SettingUp_TestClass.png)

Next what we need to do is create some tests. We do this by clicking on our test class, choosing a protocol in second from the right part of the Browser, and implementing a test. 

In case there are no protocols to choose from (this happens in cases when we are making our first test), then we need to add a new one. This is done by pressing a right click on *instance side*, going to New protocol option and picking a protocol you need (in our case tests).

![Pharo System Browser, new protocol creation pop-up menu](SettingUp_NewProtocol.png)

After we have choosen a protocol, our bottom part of System Browser will change and show a template for making methods (each test is a separate method). When giving a name it is important to put the word *test* first, so that Pharo knows that what we are making is in fact a test.

In our example, a counter will be incrementing and decrementing some value. You will notice that we are using methods which have not been created yet and that each test you write will fail (be red) when you run it. 

We can make these tests: 

**Creating MyCounter object:** 
We want to check if the object we created is not equal to nil, that is why we are using *self deny:* message. This will to a check if the statement we send is true and if it is return false. 

  
  ```GitHub
  testCreatingMyCounter
    "A test that will check if the creation of an object MyCounter is done properly"
    |tmp|
    tmp := MyCounter new.
    self deny: (tmp = nil)
  ```


**Incrementing value:** 
Here we want to check if the method *increment* is really doing his job and adding one to the value. What we did here is: created a new object MyCounter, set the test value, call the method *increment* and checked if the new value is equal to an expected result. Here we use *self assert:* key word message, which returns true if the statement is in fact true. 


```GitHub
testIncrementing
  "A test that will check if method increment is working properly. 
    Test value 5. Expected result 6."
  |counter|
  counter := MyCounter new.
  counter value: 5.
  counter increment.
  self assert: (counter value = 6)
  ```


**Decrementing value:**
Here we are checking if the method *decrement* is doing his job and subtracting one from the value. The process of creating this test is similar to previous one.


```GitHub
testDecrementing
  "A test that will check if method decrement is working properly.
   Test value 5. Expested result is 4."
  |counter|
  counter := MyCounter new.
  counter value: 5.
  counter decrement.
  self assert: (counter value = 4)
```


## Step 4. Add methods to make tests green

Now that we have create tests (which are all red), we need to implement methods that we have been testing. Switch to *MyCounter* class for this part.

The first thing that you probably have noticed already is that most of our methods are working with some kind of value. This is a number which we are assigning to our counter. Therefore, value is an instance variable of a class MyCounter. Choose your class and add this variable.

![Pharo System Browser, new variable added to class](SettingUp_AddingVariable.png)

If we have a variable, we need to assure access to it, by making *value* and *value: anInteger* methods. They will allow putting some integer as a new value (*value: anInteger*) and retrieving the current value (*value*).


```GitHub
value
  "Method that returns variable value."
  ^value
  ```
  
  
  ```GitHub
  value: anInteger
    "Method that sets *anInteger* as a variable value."
    value := anInteger
  ```


To make the first test work, we need to implement initialization of an object. Method *init* will be in initialization protocol and it will assign some default integer to the variable value.


```GitHub
init
  "Method for initialization.
  Setting variables to some default values. For example 0."
  value := 0
  ```

Now we will show the implementation on method *increment*. This method is adding one to variable value and putting this new number as value. Implementation for method *decrement* will be similar.


```GitHub
increment
  "This method adds 1 to variable value."
  self value: (value + 1)
  ```

```GitHub
decrement
  "This method subtracts 1 from variable value."	
  self value: (value - 1)
  ```

After you have added all the methods, go to your test class and run your tests. Notice that all of them are green now.

## Step 5. Create a baseline and a Metacello script

Baselines allow us to manage dependencies and specify how the repository should be loaded. We can use `Metacello` object to load the project that has a baseline defined for it. In this tutorial we will only show an example of creating a baseline for our simple `Counter` project. For more information on baselines, please read this excellent [Baselines](https://github.com/pharo-open-documentation/pharo-wiki/blob/master/General/Baselines.md) guide on Pharo Wiki.

Start by creating a package called `BaselineOf<YourProjectName>` and the class with the same name which is the subclass of `BaselineOf`. In our case, both package and class are called `BaselineOfCounter`.

```Smalltalk
BaselineOf subclass: #BaselineOfCounter
    instanceVariableNames: ''
    classVariableNames: ''
    package: 'BaselineOfCounter'
```

Now create a method `BaselineOfCounter >> baseline:` with the following content:

```Smalltalk
baseline: spec
    <baseline>
    spec for: #common do: [	
				
        "Packages"
        spec
            package: 'Counter';
            package: 'Counter-Tests' with: [ spec requires: #('Counter') ] ].
```

At this point, our baseline does not contain any external dependencies. It only says that our project consists of two packages: `Counter` and `Counter-Tests` and that the package `Counter-Tests` depends on `Counter`.

## Step 6. Create repository on GitHub

To create the repository on [GitHub](https://github.com/), first you need to visit the site and either *sign in* (if you already have an account) or *sign up* (to make a new account). Go to your profile and choose Repositories.

![Repositories menu GitHub](SettingUp_NewRepoGit.png)

In the right corner there will be a button *New*, press it to create a new repository. 

In newly opened window add name; description and README if you choose. You can also decide who will see your repository (Public - everyone; Private - you select people who will have access). After filling the necessary information, press *create repository* button.

![GitHub, new repository creation form](SettingUp_CreateNewRepo.png)

## Step 7. Load the repository into your image

## Step 8. Create an src/ folder and add metadata to your repository

It is a good practice to put all your source packages into a separate folder, usually called `src/`. This ensures that as the number of packages grows, people will not have to scroll a lot to see README. It also makes repository structure cleaner because source code is separated from documentation, licence, etc. You can navigate into the working directory of your repository and create the `src/` folder manually or execute the following line in your Playground to have Pharo create the folder for you:

```Smalltalk
(FileLocator localDirectory / 'iceberg' / '<userName>' / '<projectName>' / 'src') ensureCreateDirectory 
```

## Step 9. Add packages and do the first commit

## Step 10. Set up the continuous integration (CI)

## Step 11. Add badges to your README.md


================================================
FILE: General/Settings.md
================================================
# Settings

A Pharo developer can define **settings** to give users a way to easily customise... well, anything really.
The advantages of using the settings framework of Pharo are:
- Users can change the value of any setting defined in the image with the **Settings Browser** window. No need to build a custom UI for it.
- It is easy to add settings to an already existing application. A setting is basically just a class variable (or an instance variable of a singleton object) whose value can be set from the Settings Browser.
- No dependency. Your application does not depend on the **Pharo Settings Framework**, and the Pharo Settings Framework does not depend on your application.

## Table of Contents

* [The Settings Browser](#the-settings-browser)
* [Declaring a Setting](#declaring-a-setting)
	+ [As quick as possible](#as-quick-as-possible)
	+ [WARNING!: Default value of a setting](#warning-default-value-of-a-setting)
	+ [Elements of a Setting Declaration](#elements-of-a-setting-declaration)
		- [Id of the setting (#mySetting)](#id-of-the-setting-mysetting)
		- [Is it a setting or a group node? (setting:)](#is-it-a-setting-or-a-group-node-setting)
		- [Where is the variable this setting affects? (target:)](#where-is-the-variable-this-setting-affects-target)
		- [Label and Description (label: description:)](#label-and-description-label-description)
		- [Parent (parent:)](#parent-parent)
	+ [Other Features](#other-features)
		- [Ordering settings](#ordering-settings)
		- [Declaring optional settings](#declaring-optional-settings)
		- [Declaring a tree of settings in one method](#declaring-a-tree-of-settings-in-one-method)
		- [Providing more precise value domains](#providing-more-precise-value-domains)
			* [Declaring a range setting](#declaring-a-range-setting)
			* [Declaring a list of possible values](#declaring-a-list-of-possible-values)
		- [Launching a script](#launching-a-script)
		- [Start-up actions management](#start-up-actions-management)
		- [Extending the Settings Browser](#extending-the-settings-browser)
* [Credits](#credits)


## The Settings Browser

The Settings Browser can be opened from the Pharo menu like this:  
![Open the Settings Browser](./Settings_Image_OpenSettingsBrowser.png)  
*You can also open it by evaluating: `SettingBrowser open`*

The Settings Browser looks like this (The "Appearance" group of settings is expanded):  
![The Settings Browser](./Settings_Image_SettingsBrowser.png)

## Declaring a Setting

### As quick as possible
In this example, the main class of my application is `MyApplication`, the name of my setting is `mySetting`, and it is a boolean setting.

1. Create a `mySetting` class variable on the class `MyApplication`
```Smalltalk
Object subclass: #MyApplication
	instanceVariableNames: ''
	classVariableNames: 'mySetting'
	package: 'MyPack'
```
2. Create a getter and a setter method for it on the class, with a lazy initialisation in the getter
```Smalltalk
MyApplication class>>mySetting
	mySetting ifNil: [ mySetting := false ].
	^ mySetting
```
```Smalltalk
MyApplication class>>mySetting: aValue
	mySetting := aValue
```
3. Create a method on the `MyApplication` class, to declare the setting:
```Smalltalk
MyApplication class>>mySettingSettingsOn: aBuilder
	<systemsettings>
	(aBuilder setting: #mySetting)
		target: MyApplication;
		label: 'My Setting' translated;
		description: 'A very important setting for my application';
		parent: nil.
```
4. Tada!
![MySetting](./Settings_Image_MySetting.png)


### WARNING!: Default value of a setting

**A setting variable must never be `nil`!**

To display a setting, the Settings Browser chooses a widget based on the value of the setting variable (boolean -> check box, colour -> colour-picker, integer -> text field...). If the variable of a setting is worth `nil`, the Settings Browser cannot choose a widget.

The prefered method of ensuring the setting variable is initialised is by setting a lazy initialisation in the accessor method. This is because it also covers the case where the user resets the setting to its default value in the Settings Browser (the variable is set to `nil` in this case).

If this is not possible, then a default value can be indicated in the setting declaration. Example:  
```Smalltalk
(aBuilder setting: #caseSensitiveFinds)
	default:true;
	...
```


### Elements of a Setting Declaration
Here is an example of a setting declaration. Below is a breakdown of its elements.
```Smalltalk
MyApplication class>>mySettingSettingsOn: aBuilder
	<systemsettings>
	(aBuilder setting: #mySetting)
		target: MyApplication;
		label: 'My Setting' translated;
		description: 'A very important setting for my application' translated;
		parent: nil.
```

#### Id of the setting (#mySetting)
The id of the setting. It is used to:
- compute the names of the getter/setter methods to call to change the setting
- for other settings to define this node as their parent in the settings tree (more on that later)

Example:
```Smalltalk
(aBuilder setting: #mySetting)
```  
In this example, the computed name of the getter method is `mySetting`. The computed name of the setter method is `mySetting:`.

#### Is it a setting or a group node? (setting:)
The settings are arranged as a tree. Some nodes show a value that can be changed (like the #mySetting we just defined): these are **settings nodes**. Other nodes are just there for organisation purposes: these are **group nodes**.

- Declaring a setting node:  
```Smalltalk
(aBuilder setting: #mySetting)
```  
Result:  
![MySetting](./Settings_Image_MySettingSettingNode.png)
- Declaring a group node:  
```Smalltalk
(aBuilder group: #mySetting)
```  
Result:  
![MySetting group node](./Settings_Image_MySettingGroupNode.png)

#### Where is the variable this setting affects? (target:)
- If the setting is a **class variable**, the **target** of this setting is the class on which the variable is defined. Example:
```Smalltalk
target: MyApplication;
```
- If the setting is an **instance variable of a singleton instance**, the **target** of the setting is the class of the Singleton, and its **targetSelector** is the name of the method to call on that class to get the singleton instance. Example:
```Smalltalk
target: MySingleton;
targetSelector: #getCurrentInstance;
```
In this example, when the settings framework will look for the variable holder, it will send `#getCurrentInstance` to `MySingleton`.

#### Label and Description (label: description:)
These should be self-explanatory from the pictures. Example:
```Smalltalk
label: 'My Setting' translated;
description: 'A very important setting for my application' translated;
```  
Sending `translated` will greatly facilitate the translation into other languages.


#### Parent (parent:)
To declare a setting node as a children of another, set its parent property to the id of its parent node. Example: (imagine another setting called `mySettingGroup` is defined elsewhere)
```Smalltalk
parent: #mySettingGroup
```  
Result:  
![Another setting node as parent](./Settings_Image_Parent.png)


### Other Features

#### Ordering settings
By default, sibling settings are sorted alphabetically by their label. To change this, you can:
- add `noOrdering` to the declaration of a group node, so that its children setting get ordered in the order in which they were declared. Example:
```Smalltalk
appearanceSettingsOn: aBuilder
	<systemsettings>
	(aBuildergroup:#appearance)
		label: 'Appearance' translated;
		noOrdering;
		with: [... ]
```
- add `order:` (with a float or integer) to the declaration of a setting. Nodes with an order number are always placed before others and are sorted according to their respective order number. If an order is given to an item, then no ordering is applied for other siblings. Example:
```Smalltalk
(aBuilder group: #standardFonts)
	label: 'Standard fonts' translated;
	with: [
		(aBuilder launcher: #updateFromSystem)
			order:1;
			label: 'Update fonts from system' translated.
		(aBuilder setting: #defaultFont)
			label: 'Default' translated.
		(aBuilder setting: #codeFont)
			label: 'Code' translated.
```

#### Declaring optional settings
Sometimes, some settings do not make sense in all situations. For example, a setting to ask for a second background colour only makes sense if the user selected a gradient as background.  
Settings whose parent is a boolean setting set to `false` will not be shown in the Settings Browser.

#### Declaring a tree of settings in one method
Use the `with:` methods to nest setting declarations. Nested settings will have the setting they are nested in as parent. Example:

```Smalltalk
RBConfigurableFormatter class>>settingsOn: aBuilder
	<systemsettings>
	(aBuilder group: #configurableFormatter)
		target: self;
		label: 'Configurable Formatter' translated;
		with:[
			(aBuilder setting: #formatCommentWithStatements)
				label: 'Format comment with statements' translated.
			(aBuilder setting: #indentString)
				label: 'Indent string' translated]
```  
Result:  
![Nested Declaration Result](./Settings_Image_NestedDeclarationsResult.png)

#### Providing more precise value domains
By default, the possible value set of a preference is not restricted and is given by the actual type of the preference. For example, for a color preference, the widget allows you to choose whatever color. For a number, the widget allows the user to enter any number. But in some cases, only a particular set of values is desired. There are two ways to do this:
- Declaring a range setting
- Declaring a list of possible values

##### Declaring a range setting
1. use `range:` as the type of setting, instead of `setting:` or `group:`
2. set the `range:` property of the setting (for example: `range: (-5 to: 100)`)

Example:
```Smalltalk
screenMarginSettingOn: aBuilder
	<systemsettings>
	(aBuilder range: #fullScreenMargin)
		target: SystemWindow;
		parent: #windows;
		label: 'Full screen margin' translated;
		range:(-5 to: 100).
```  
Result:  
![Range Setting](./Settings_Image_RangeSetting.png)

##### Declaring a list of possible values
1. use `pickOne:` as the type of setting, instead of `setting:` or `group:`
2. set the `domainValues:` property of the setting to the list of possible values (for example: `domainValues: #(#'Reverse Stagger' #Cascade #Standard)`)

Example:
```Smalltalk
windowPositionStrategySettingsOn: aBuilder
	<systemsettings>
	(aBuilder pickOne: #usedStrategy)
		label: 'Window position strategy' translated;
		target: RealEstateAgent;
		domainValues: #(#'Reverse Stagger' #Cascade #Standard)
```  
Result:  
![List of Possible Values](./Settings_Image_ListOfPossibleValues.png)

For `domainValues:`, you can provide a list of **associations** instead of a list of values. In the Settings Browser, the user will select a value among the keys of these associations, but the setting variable will actually be set to the value corresponding to the selected key, not to the key itself.

Example:  
```Smalltalk
domainValues: {'Big' translated -> 25. 'Medium' translated -> 12. 'Small' -> 5}
```  
Result:  
In the Settings Browser, the user will choose between "Big", "Medium" and "Small", but the variable corresponding to the setting will actually be set to 25, 12 or 5 respectively.

The list of possible values **does not have to be static**. You can declare a piece of code that computes the list. It will be executed every time the Settings Browser is opened.  

Example:
```Smalltalk
domainValues: (UITheme allThemeClasses collect: [:c | c themeName -> c])
```

#### Launching a script
Imagine that you want to launch an external configuration tool or that you want to allow one to configure the system or a particular package with the help of a script. In such a case you can declare a *launcher*. A launcher is shown with a label as a regular setting except that no value is to be entered for it. Instead, a button labelled *Launch* is integrated in the Settings Browser and clicking on it launch an associated script.

Illustration: 
![Launching a Script](./Settings_Image_LaunchingAScript.png)

*More information in section 5.6 "Launching a script" of the [Deep Into Pharo book](http://books.pharo.org/deep-into-pharo/).*

#### Start-up actions management

Even if many preferences have been removed from Pharo because they were obsolete, there are a still a large number of them. And even if the Settings Browser is easy to use, it may be tedious to set up your own preferences even for a subset, each time you start working with a new image. A solution is to implement a script to set all your preferred choices. The best way is to create a specific class for that purpose. You can then include it in a package that you can reload each time you want to setup a fresh image. We call this kind of class a *Setting style*.  
To manage *Setting styles*, the Settings Browser can be helpful in two ways. First, it can help you discover how to change a preference value, and second, it can create and update a particular style for you.

*More information in section 5.7 "Start-up actions management" of the [Deep Into Pharo book](http://books.pharo.org/deep-into-pharo/).*

#### Extending the Settings Browser

The Settings Browser is by default able to manage simple preference types. These default possibilities are generally enough. But there are some situations where it can be very helpful to be able to handle more complex preference values.  
As an example, let us focus on the text selection preferences. We have the primary selection and three other optional kinds of text  selection, the secondary selection, the ‘find and replace’ selection and the selection bar. For all selections, a background color can be set. For the primary, the secondaryand the find and replace selection, a text color can also be chosen.

*More information in section 5.8 "Extending the Settings Browser" of the [Deep Into Pharo book](http://books.pharo.org/deep-into-pharo/).*

## Credits
Thomas Dupriez.  
This page is based on chapter 5 of the [Deep Into Pharo book](http://books.pharo.org/deep-into-pharo/): The Settings Framework  

================================================
FILE: General/SortingCollections.md
================================================
# Sorting collections

A common requirement in software engineering is to sort collections. This page provides information on how to sort collections in Pharo.

- [Sorting API](#sorting-api)
  * [Sort a collection](#sort-a-collection)
  * [Keep a collection sorted](#keep-a-collection-sorted)
- [Sort functions](#sort-functions)
- [Sorting via a block](#sorting-via-a-block)

## Sorting API

Pharo's Collections come with an API to sort them. In this section, we will present some of it and explain their difference.

The default sorting implemented on Pharo's collection is a merge sort. Merge sort worst-case complexity is `O(N log N)`. This sorting algorithm usually does only half as many comparisons as heapsort or quicksort.

### Sort a collection 

The two main methods to sort a collection are `#sort:` and `#sorted:`. Those two methods are taking a block or a sort function as parameter (those are explained later in this page) and return a collection sorted based on the parameter.
The difference between the two methods is that `#sort:` sort the receiver when the `#sorted:` method sorts a copy of the receiver.

```Smalltalk
#(1 2 4 7 3 6 4) sort: #yourself ascending. "#(1 2 3 4 4 6 7) <= This result is the receiver"
#(1 2 4 7 3 6 4) sorted: #yourself ascending. "#(1 2 3 4 4 6 7) <= This result is a copy of the receiver"
```

Those two methods also have an equivalent without argument, `#sort` and `#sorted` that sort the collection using the `#<=` comparison operator.

The API described here will sort a collection at one point but new elements added to the collection will not be sorted. If you wish to keep a collection sorted, you should use `SortedCollection` as explained in the next section.

> Warning: If not absolutely needed, one should not use `SortedCollection` because it might impact performances of your software when adding and removing items to the collection.

### Keep a collection sorted

In case you want to keep a collection sorted, you should use a `SortedCollection`. This collection is configured with a sort block or sort function and will sort all new elements added to the collection.

You can transform a collection into sorted collection using `#asSortedCollection:` or `#asSortedCollection`. 

```Smalltalk
(#(1 2 4 7 3 6 4) asSortedCollection: #yourself ascending)
	add: 2;
	yourself "a SortedCollection(1 2 2 3 4 4 6 7)"
```

You can also instantiate yourself the sorted collection:

```Smalltalk
(SortedCollection sortUsing: #yourself ascending)
	addAll: #(1 2 4 7 3 6 4);
	yourself "a SortedCollection(1 2 3 4 4 6 7)"
```

```Smalltalk
(SortedCollection sortBlock: [ :a :b | a < b ])
	addAll: #(1 2 4 7 3 6 4);
	yourself "a SortedCollection(1 2 3 4 4 6 7)"
```

> Note: #sortUsing: was introduced in Pharo 8. In previous versions it is possible to use #sortBlock: for both sort block and sort functions.

## Sort functions

The first way to sort a collection is to use a sort function. A sort function is an object configuring how to sort a collection. They can be created in different ways and can be composed. 

You can create a sort function using a property and a direction:

```Smalltalk
#('longstring' 'test' 'test2') sorted: #size ascending. "#('test' 'test2' 'longstring')"
#('longstring' 'test' 'test2') sorted: [ :string | string size ] descending "#('longstring' 'test2' 'test')"
```

```Smalltalk
#(#(1 2) #(2 3) #(0 0)) sorted: [:sequence | sequence inject: 0 into: [:sum :each | sum + each] ] descending. "#(#(2 3) #(1 2) #(0 0))"
```

You can use 2 arguments blocks, for cases where the function isn't expressible with objects that respond to `<` and `=`. The only catch is that such a function should return true or false, but a collation order instead, values of -1 (for before), 0 (the same) or 1 (to follow). For example:

```Smalltalk
| oddBlock |
oddBlock := [ :a :b | a odd = b odd ifTrue: [ 0 ] ifFalse: [ a odd ifTrue: [ -1 ] ifFalse: [ 1 ] ] ].
#(1 5 1 3 2 7 9 4 6) asSortedCollection: oddBlock descending	"a SortedCollection(6 2 4 3 1 7 9 5 1)"
```

Since Pharo 8, it is also possible to express the previous sort function using a property returning a boolean:

```Smalltalk
#(1 5 1 3 2 7 9 4 6) asSortedCollection: #odd ascending	"a SortedCollection(6 2 4 3 1 7 9 5 1)"
```

In this case, the elements answering `false` will be placed before the elements answering true in the ascending order. This is explained by the fact that the function will sort the booleans according to their bit value (0 or 1).

> If you wish to use this feature in a version earlier than Pharo 8, you can add this method as an [extension](Extensions.md) of the Boolean class:

```Smalltalk
threeWayCompareTo: anotherObject
	^ self asBit threeWayCompareTo: anotherObject asBit
```

Using #undefinedFirst and #undefinedLast it is possible to deal with nil values, moving them first or last. For Example:

```Smalltalk
#(a nil z b) sorted: #value ascending undefinedFirst. "#(nil #a #b #z)"
#(a nil z b) sorted: #value ascending undefinedLast. "#(#a #b #z nil)"
```

Finally, you can use a chained sorted function in case you have elements of the same priority in the first sort function.

In this next example, we sort by size and for elements of same size we sort by alphabetical order:

```Smalltalk
#('test' 'toto1' 'test2' 'toto') sorted: #size ascending, #yourself ascending "#('test' 'toto' 'test2' 'toto1')"
```

## Sorting via a block

The second way to sort a collection is to use a sort block. A sort block takes two elements of the collection as parameter and should return a boolean describing if the first one should be before the second one.

```Smalltalk
#('longstring' 'test' 'test2') sorted: [ :string1 :string2 | string1 size < string2 size ]. "#('test' 'test2' 'longstring')"
```


================================================
FILE: General/Traits.md
================================================
# Traits

- [Description](#description)
- [Create and use a new Trait](#create-and-use-a-new-trait)
- [Abstract methods](#abstract-methods)
- [Stateful traits](#stateful-traits)
- [Traits initialization](#traits-initialization)
- [Customize method received from a Trait](#customize-method-received-from-a-trait)
  * [Reject some methods received from the trait](#reject-some-methods-received-from-the-trait)
  * [Alias some methods received from the trait](#alias-some-methods-received-from-the-trait)
- [Customize instance variables received from a (stateful) Trait](#customize-instance-variables-received-from-a-stateful-trait)
  * [Reject some instance variables received from the trait](#reject-some-instance-variables-received-from-the-trait)
  * [Alias some instance variables received from the trait](#alias-some-instance-variables-received-from-the-trait)
- [Trait composition](#trait-composition)
- [Conflicts](#conflicts)

## Description

Traits are pure units of behavior that can be composed to form classes or other traits. The trait composition mechanism is an alternative to multiple or mixin inheritance in which the composer has full control over the trait composition. It enables more reuse than single inheritance without introducing the drawbacks of multiple or mixin inheritance.

Pharo 7's Traits are modular and not tied to the Kernel. So it would be possible to have multiple implementations.

## Create and use a new Trait

Creation of a new Trait is close to the creation of a new class. It is done in a programatic way:

```Smalltalk
Trait named: #TNameOfMyTrait
	uses: {}
	package: 'MyPackage'
```

This will create a new Trait called `TNameOfMyTrait` stored in `MyPackage`.

Concrete example:

```Smalltalk
Trait named: #FamixTWithEnumValues
	uses: {}
	slots: {}
	package: 'Famix-Traits-EnumValue'
```

> Calypso provides a menu entry to create traits. To access it, right-click on the classes list (with no class or trait selected) and select "New trait".

> **Warning**: In Pharo < 8, the message `#named:uses:slots:package:` should be replaced by `#named:uses:slots:category:`.  

Then you add a new method to the Trait, just as you would implement a method in a class. All classes using this trait will be able to use methods created in the Traits except if for methods overriden by the class.

To use your Trait you just need to declare it in the class declaration as parameter of the `#uses:` keyword. 

```Smalltalk
MySuperClass subclass: #MyClass
	uses: TNameOfMyTrait
	slots: {  }
	classVariables: {  }
	package: 'MyPackage'
```

Concrete example:

```Smalltalk
FAMIXType subclass: #FAMIXEnum
	uses: FamixTWithEnumValues
	slots: {  }
	classVariables: {  }
	package: 'Famix-Compatibility-Entities'
```

You can also use multiple Traits with your class with the `#+` message.

```Smalltalk
MySuperClass subclass: #MyClass
	uses: TNameOfMyTrait + TNameOfMySecondTrait
	slots: {  }
	classVariables: {  }
	package: 'MyPackage'
```

## Abstract methods

We might need to call a method for which the implementation will be specific to the class using the trait. To manage this case, a Trait can hold methods that explicitely declare that user should define it. These methods contain a call to `#explicitRequirement` message.

```Smalltalk
TMyTrait>>addButton: aButton
	self buttons add: aButton
```

```Smalltalk
TMyTrait>>buttons
	^ self explicitRequirement
```

> Some Pharo developers create Traits with all their methods calling `#explicitRequirement` message. Doing this kind of simulate an interface (as Java's interfaces). Users of one of these traits thus declare that they support the interface it defines and override all methods defined by the trait.

## Stateful traits

Since Pharo 7, it is possible to add instance variables or a slot to Traits. This will make you trait a stateful trait. 

Examples:

```Smalltalk
Trait named: #MDLWithConfigurableRightPanel
	uses: {}
	slots: { #panelComponent. #toolbar }
	package: 'MaterialDesignLite-Extensions'
```

```Smalltalk
Trait named: #FamixTWithEnumValues
	uses: {}
	slots: { #enumValues => FMMany type: #FamixTEnumValue opposite: #parentEnum }
	package: 'Famix-Traits-EnumValue'
```

## Traits initialization

Traits do not include a way to initialize classes using them, it relies on conventions.

One way to manage this might be to implement a method named `initializeTMyTraitName` on each traits needing an initialization and to call all those methods on the class using them.

In case of trait composition (See [Trait composition](#trait-composition)), a trait composed of other traits can also implement a initialize method calling the one of the Traits it includes.

## Customize method received from a Trait
When a class uses a trait, it is possible for it to reject or alias some methods.

### Reject some methods received from the trait
In some case it is needed to reject a method of a Trait. It can be achieved using `#-` message.

```Smalltalk
TestCase subclass: #StackTest
	uses: TEmptyTest - {#testIfNotEmptyifEmpty. #testIfEmpty. #testNotEmpty} + (TCloneTest - {#testCopyNonEmpty})
	slots: { #empty. #nonEmpty }
	classVariables: {  }
	package: 'Collections-Tests-Stack'
```

### Alias some methods received from the trait
It is possible to alias some methods received from a trait. If, for example you alias `#aliasedMethod` with `#methodAlias` as shown below, your class will hold both `#methodAlias` and `#aliasedMethod`.

```
Object subclass: #MyObjectUsingTraitByAliasingMethod
	uses: TTraitToBeUsed @ { #methodAlias -> #aliasedMethod }
	slots: {  }
	classVariables: {  }
	package: 'TestTraitAliasing'
```

Here is a simple example. Consider a situation when a trait `TLocated` implements a method `moveTo:` that defines the movement of an object to a given cell. The user of this trait needs to implement the post-movement operation. Usually, this would be done by overriding the `moveTo:` method and calling `super moveTo: aCell` in the first line of the new implementation. However, the super calls can not be used with traits as they install methods directly into the code of their users. The simple workaround would be to create an allias `basicMoveTo:` for the trait method and then call it from the new `moveTo:` method implemented by the user class:

```st
TLocated >> moveTo: aCell
    "Define the movement"

Object subclass: #Antelope
    uses: TLocated @ { #basicMoveTo: -> #moveTo: }
    ...

Antelope >> moveTo: aCell
    self basicMoveTo: aCell.
    "Do some post-movement actions"
```

## Customize instance variables received from a (stateful) Trait
When a class uses a trait, it is possible for it to reject or alias some instance variables.

### Reject some instance variables received from the trait
In some case it is needed to reject an instance variable of a Trait. It can be achieved using `#--` message. It works similarly to methods rejecting explaining in previous section.

```
Object subclass: #MyObjectUsingTraitByRejectingInstVar
	uses: TTraitToBeUsed asTraitComposition -- #instVarNameToRemove
	slots: {  }
	classVariables: {  }
	package: 'TestTraitAliasing'
```

> `#asTraitComposition` needs to sent to the trait because `#--` message is not understood by trait but by trait composition.

### Alias some instance variables received from the trait
It is possible to alias some instance variables received from a trait. If, for example you alias `#aliasedInstVar` with `#instVarAlias` as shown below, your class will hold both `#instVarAlias` and `#aliasedInstVar`.

```
Object subclass: #MyObjectUsingTraitByAliasingInstVar
	uses: (TTraitToBeUsed >> { #instVarAlias -> #aliasedInstVar })
	slots: {  }
	classVariables: {  }
	package: 'TestTraitAliasing'
```

## Trait composition

Traits are composable, this mean that you can have Traits using other traits. It is done in the same way than class using a Trait:

```Smalltalk
Trait named: TMyComposedTrait
	uses: TMyFirstTrait + TMySecondTrait
	package: 'MyPackage'
```

Example:

```Smalltalk
Trait named: #EpTEventVisitor
	uses: EpTCodeChangeVisitor
	package: 'Epicea-Visitors'
```
## Conflicts

Two kinds of *conflicts* can happen with methods implemented on Traits.

1. A method is present on a used Trait, but the class using this Trait also implements this method. In that case, the method lookup will select the method from the class. It is an equivalent of an override of method.

2. Two traits implementing the same method are used. In that case, if the method is called it will raise an error `traitConflict`.

A way to solve both cases is to use method aliasing and to remove the conflicting method:
```Smalltalk
Object subclass: #MyObjectUsingTraitByAliasingMethod
	uses: TTraitToBeUsed @ { #methodAlias -> #conflictingMethod } - { #conflictingMethod }
	slots: {  }
	classVariables: {  }
	package: 'TestTraitAliasing'
```

Another way to solve case 2. is to implement a method on the class using the trait in order to chose the behavior wanted.


================================================
FILE: General/Travis.md
================================================
# Setting up Travis Continuous Integration

> IMPORTANT NOTE: Since Travis is becoming a pay to use service, it is possible that this documentation will not be updated anymore.
> [A page on how to use Github Actions](GithubActions.md) in order to have a continuous integration is already available on this wiki.

Your repository should have two extra hidden files: `.travis.yml` and `.smalltalk.ston`.
In addition, you may want to have a `.coveralls` configuration to support automatic coverage computation.

# `.travis.yml`
Here is a basic `.travis.yml` that configure travis to create a matrix to run your projects tests on both linux and osx plateforms and for both Pharo 8.0 and Pharo 7.0 64 bits.

```yaml
language: smalltalk
sudo: false

os:
  - linux
  - osx

smalltalk:
  - Pharo64-8.0
  - Pharo64-7.0
```

# `.smalltalk.ston`
`.smalltalk.ston` is the file where you specify the baseline to use for your project and the packages containing the tests (used to compute coverage).

```
SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'EnlumineurFormatter',
      #directory : 'src',
      #platforms : [ #pharo ]
    }
  ],
  #testing : {
    #coverage : {
      #packages : [ 'EnlumineurFormatter-Tests' ]
    }
  }
}
```

# `.coveralls.yml`
If one have a coveralls account, one can add a `.coveralls.yml` file with the coveralls token of their project.


```yaml
service_name: travis-pro
repo_token: twxvbgLWXzoj3syZg3eaYfBZxCKEbensg
```


================================================
FILE: General/TweakingBigImages.md
================================================
# Tweaking big images

Pharo is special in the sense that the language and IDE are mixed. It means that your application runs together with the IDE.
In some cases, it leads to Pharo images consuming a large amount of memory (aka Big Images). 
The goal of this page is to sum up some tweaking that can be done on Pharo images to improve the performances of such images. 

* [Fast dragging](#fast-dragging)
* [Disable taskbar previews](#disable-taskbar-previews)
* [Tune Garbage Collection](#tune-garbage-collection)
* [Disable Quality Assistant plugin](#disable-quality-assistant-plugin)
* [Disable Spotter plugins](#disable-spotter-plugins)
* [Disable Epicea](#disable-epicea)

## Fast dragging

While dragging windows in Pharo, an animation is run. This animation is not performant and can make the dragging of windows slow in large images.

As a workaround, it is possible to solve this problem by enabling a "fast dragging" option:

```Smalltalk
UITheme currentSettings fastDragging: true
```

> Remark: This option is reset when one change the theme Pharo. Thus, you should execute this code snippet each time you update the theme.

## Disable taskbar previews

While going over the taskbar of Pharo, previews of the images are displayed. This feature can be really slow on big images. 
It is possible to disable it:

```Smalltalk
TaskbarMorph showWindowPreview: false
```

## Tune Garbage Collection 

Pharo is a language using a [garbage collector](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) for its memory management. 
When objects are created, memory is allocated for them. Once in a while, the memory is cleaned and the garbage collector frees the memory of objects that are not used anymore.

This process can be customized via multiple parameters. To understand the impact of those parameters we explain here how garbage collection works in Pharo.

Because most objects usage stops quickly after their instantiation (we say they have a short life-time), Pharo memory (aka "the heap") is divided into multiple spaces:
- The "Old space" contains objects that survived multiples garbage collections (GC). When it is filled, new memory segments are allocated to the old space.
- The "New Space" contains recently created objects. 

The "New Space" is divided into 3 sub spaces:
- The "Eden" containing the newest objects created (taking 5/7 of the new space)
- Two survivors spaces (1/7 of the new space each) contains the object that survived some garbage collection already

The Garbage Collector execute two kind of cleanings:
- The **scavenge** happens when the Eden is filled at a certain ratio and will clean the Eden. When objects from the eden are still referenced, they are moved to the survivors. There are two kinds of survivors: past survivor space and future survivor space (past space and future space for short). Past and future space swap after each scavenge, which empties eden and past space, copying survivors into future space, tenuring overflow to old space and then making future space the new past space. When the survivor space is fill at more than 90%, the survivors are moved to the old space.
- The **full garbage collect** (aka full GC) happens when the heap grow past a certain ratio. It will go through the old space and clean the old objects.

We can customize multiple parameters.

The size of the new space can be increased. When it increases, scavenges will happen less often.
This can increase a lot the speed of algorithm creating a lot of new objects. 

The size of the eden can be accessed via the vm parameter 44. The desired size of the new space can be set via the vm parameter 45. 

By default, the new space size is 3.8Mo. It can be increased to 32 or 64Mo if you have enough memory.

```Smalltalk
Smalltalk vm parameterAt: 44. "9057248"
Smalltalk vm parameterAt: 45 put: 64 * 1024 * 1024
```

> Since the eden size is fixed at startup, this change requires to restart the image.

If you create at some point a lot of objects that will stay for a while, you can increase the size of new memory segments to allocate in order to spend less time to allocate memory. 

By default the growth is of 16Mo.

```Smalltalk
Smalltalk vm parameterAt: 25 put: 32 * 1024 * 1024
```

If your memory needs to grow and shrink a lot, you can also increase the memory threshold above which shrinking object memory happens. 

By default, 32Mo.

```Smalltalk
Smalltalk vm parameterAt: 24 put: 64 * 1024 * 1024
```

You can also increase the ratio of growth and image size at or above which a GC will be performed	post scavenge.

By default, 0.33. This parameter needs to be a float. 

If you use a really high ratio such as 200.0+, no full GC will happen.

```Smalltalk
Smalltalk vm parameterAt: 55 put: 0.7
```

> Note: Those 3 last parameters are reset during image startup. 
> In order to maintain them, you can use startup actions. See [Session management documentation](SessionsManagement.md).

> This might change in the future (https://github.com/OpenSmalltalk/opensmalltalk-vm/issues/477).

By tweaking those parameters, algorithm that took 9min30 before are now taking less than 5min with images of 1.3Go.

Thanks to [Eliot Miranda](http://www.mirandabanda.org/cogblog/microbio/) and [Clément Bera](https://clementbera.wordpress.com/) for the explanations.

For more information: [https://clementbera.wordpress.com/2017/03/12/tuning-the-pharo-garbage-collector](https://clementbera.wordpress.com/2017/03/12/tuning-the-pharo-garbage-collector)

## Disable Quality Assistant plugin

The code browser in Pharo has a plugin to display code critics. This plugin can take some time to compute the rules in case of large images. It is possible to disable it:

```Smalltalk
ClyCriticBrowserPlugin disable
```

## Disable Spotter plugins

Pharo's spotter has many plugins to search for and display results of mny kind.

Some of those searchs can be long to compute in big images. It is possible to disable the extensions that do not interest us.

You can find the list of extensions executing:

```Smalltalk
GTSpotter spotterExtendingMethods
```

Then you caqn disable an extension. For example if you have poor network you can disable the extension looking for projects in the Pharo catalog.

```Smalltalk
GTSpotterExtensionSettings disabledExtensions add: 'GTSpotter_spotterCatalogProjectsFor'
```

The name of the extension to disable should be of this form: `ClassContainingTheExtension_nameOfTheMethodWithoutLastSemicolon`.

In case of images with a lot of code, it is possible that many projects extend the world menu. In this case the world menu plugin can be long to search. You can diable it this way:

```Smalltalk
GTSpotterExtensionSettings disabledExtensions add: 'GTSpotter_spotterWorldMenuFor'
```

The extensions to disable will most probably depend on what fills the size of your image. Look through the list and estimate what can take timefor you and what do not interest you. 

## Disable Epicea

When you compile code, all the changes are persisted in files by the **Epicea** tool. This allows one to revert/replay changes and to get back lost changes in case an image crash. 

Disabling Epicea can speed up the work in large images:

```Smalltalk
EpMonitor reset
````

> WARNING: Disabling Epicea will remove the possibility to replay changes in case your image crash. Disable it only if necessary!


================================================
FILE: General/Windows10SubsystemForLinux.md
================================================
# How to get Pharo running on WSL

Pharo can be run under Windows 10 Subsystem for Linux (WSL).

- Install WSL (see [microsoft documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10))
- Install X Server for Windows (I used [VcXsrv](https://sourceforge.net/projects/vcxsrv/)).
- Install [Mesa](https://wiki.debian.org/Mesa) with `sudo apt install mesa-utils` (needed because there are missing libraries for the x11 display used by Pharo).
> Note: The Mesa dependency may be overkill. On the [Pharo install page](https://pharo.org/web/gnu-linux-installation-64) there's mention of some things to do for Ubuntu 16. 
- Install Pharo:

```bash
$ mkdir MyPharo
$ cd MyPharo/
$ curl -L https://get.pharo.org/64/ | bash
```

The last step can also be the Pharo Launcher.

> Note: Last time it has been tested, only Pharo of version >= 6 64bit could be run.
> Pharo 32bits is not compatible because of a missing part of the kernel.

For other Pharo/WSL issues, see [this blog](https://fuhrmanator.github.io/2019/02/27/Pharo-in-WSL.html). 


================================================
FILE: LICENSE
================================================
Copyright (c) 2018 pharo-wiki

Attribution 4.0 International

=======================================================================

Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.

Using Creative Commons Public Licenses

Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.

     Considerations for licensors: Our public licenses are
     intended for use by those authorized to give the public
     permission to use material in ways otherwise restricted by
     copyright and certain other rights. Our licenses are
     irrevocable. Licensors should read and understand the terms
     and conditions of the license they choose before applying it.
     Licensors should also secure all rights necessary before
     applying our licenses so that the public can reuse the
     material as expected. Licensors should clearly mark any
     material not subject to the license. This includes other CC-
     licensed material, or material used under an exception or
     limitation to copyright. More considerations for licensors:
	wiki.creativecommons.org/Considerations_for_licensors

     Considerations for the public: By using one of our public
     licenses, a licensor grants the public permission to use the
     licensed material under specified terms and conditions. If
     the licensor's permission is not necessary for any reason--for
     example, because of any applicable exception or limitation to
     copyright--then that use is not regulated by the license. Our
     licenses grant only permissions under copyright and certain
     other rights that a licensor has authority to grant. Use of
     the licensed material may still be restricted for other
     reasons, including because others have copyright or other
     rights in the material. A licensor may make special requests,
     such as asking that all changes be marked or described.
     Although not required by our licenses, you are encouraged to
     respect those requests where reasonable. More_considerations
     for the public:
	wiki.creativecommons.org/Considerations_for_licensees

=======================================================================

Creative Commons Attribution 4.0 International Public License

By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution 4.0 International Public License ("Public License"). To the
extent this Public License may be interpreted as a contract, You are
granted the Licensed Rights in consideration of Your acceptance of
these terms and conditions, and the Licensor grants You such rights in
consideration of benefits the Licensor receives from making the
Licensed Material available under these terms and conditions.


Section 1 -- Definitions.

  a. Adapted Material means material subject to Copyright and Similar
     Rights that is derived from or based upon the Licensed Material
     and in which the Licensed Material is translated, altered,
     arranged, transformed, or otherwise modified in a manner requiring
     permission under the Copyright and Similar Rights held by the
     Licensor. For purposes of this Public License, where the Licensed
     Material is a musical work, performance, or sound recording,
     Adapted Material is always produced where the Licensed Material is
     synched in timed relation with a moving image.

  b. Adapter's License means the license You apply to Your Copyright
     and Similar Rights in Your contributions to Adapted Material in
     accordance with the terms and conditions of this Public License.

  c. Copyright and Similar Rights means copyright and/or similar rights
     closely related to copyright including, without limitation,
     performance, broadcast, sound recording, and Sui Generis Database
     Rights, without regard to how the rights are labeled or
     categorized. For purposes of this Public License, the rights
     specified in Section 2(b)(1)-(2) are not Copyright and Similar
     Rights.

  d. Effective Technological Measures means those measures that, in the
     absence of proper authority, may not be circumvented under laws
     fulfilling obligations under Article 11 of the WIPO Copyright
     Treaty adopted on December 20, 1996, and/or similar international
     agreements.

  e. Exceptions and Limitations means fair use, fair dealing, and/or
     any other exception or limitation to Copyright and Similar Rights
     that applies to Your use of the Licensed Material.

  f. Licensed Material means the artistic or literary work, database,
     or other material to which the Licensor applied this Public
     License.

  g. Licensed Rights means the rights granted to You subject to the
     terms and conditions of this Public License, which are limited to
     all Copyright and Similar Rights that apply to Your use of the
     Licensed Material and that the Licensor has authority to license.

  h. Licensor means the individual(s) or entity(ies) granting rights
     under this Public License.

  i. Share means to provide material to the public by any means or
     process that requires permission under the Licensed Rights, such
     as reproduction, public display, public performance, distribution,
     dissemination, communication, or importation, and to make material
     available to the public including in ways that members of the
     public may access the material from a place and at a time
     individually chosen by them.

  j. Sui Generis Database Rights means rights other than copyright
     resulting from Directive 96/9/EC of the European Parliament and of
     the Council of 11 March 1996 on the legal protection of databases,
     as amended and/or succeeded, as well as other essentially
     equivalent rights anywhere in the world.

  k. You means the individual or entity exercising the Licensed Rights
     under this Public License. Your has a corresponding meaning.


Section 2 -- Scope.

  a. License grant.

       1. Subject to the terms and conditions of this Public License,
          the Licensor hereby grants You a worldwide, royalty-free,
          non-sublicensable, non-exclusive, irrevocable license to
          exercise the Licensed Rights in the Licensed Material to:

            a. reproduce and Share the Licensed Material, in whole or
               in part; and

            b. produce, reproduce, and Share Adapted Material.

       2. Exceptions and Limitations. For the avoidance of doubt, where
          Exceptions and Limitations apply to Your use, this Public
          License does not apply, and You do not need to comply with
          its terms and conditions.

       3. Term. The term of this Public License is specified in Section
          6(a).

       4. Media and formats; technical modifications allowed. The
          Licensor authorizes You to exercise the Licensed Rights in
          all media and formats whether now known or hereafter created,
          and to make technical modifications necessary to do so. The
          Licensor waives and/or agrees not to assert any right or
          authority to forbid You from making technical modifications
          necessary to exercise the Licensed Rights, including
          technical modifications necessary to circumvent Effective
          Technological Measures. For purposes of this Public License,
          simply making modifications authorized by this Section 2(a)
          (4) never produces Adapted Material.

       5. Downstream recipients.

            a. Offer from the Licensor -- Licensed Material. Every
               recipient of the Licensed Material automatically
               receives an offer from the Licensor to exercise the
               Licensed Rights under the terms and conditions of this
               Public License.

            b. No downstream restrictions. You may not offer or impose
               any additional or different terms or conditions on, or
               apply any Effective Technological Measures to, the
               Licensed Material if doing so restricts exercise of the
               Licensed Rights by any recipient of the Licensed
               Material.

       6. No endorsement. Nothing in this Public License constitutes or
          may be construed as permission to assert or imply that You
          are, or that Your use of the Licensed Material is, connected
          with, or sponsored, endorsed, or granted official status by,
          the Licensor or others designated to receive attribution as
          provided in Section 3(a)(1)(A)(i).

  b. Other rights.

       1. Moral rights, such as the right of integrity, are not
          licensed under this Public License, nor are publicity,
          privacy, and/or other similar personality rights; however, to
          the extent possible, the Licensor waives and/or agrees not to
          assert any such rights held by the Licensor to the limited
          extent necessary to allow You to exercise the Licensed
          Rights, but not otherwise.

       2. Patent and trademark rights are not licensed under this
          Public License.

       3. To the extent possible, the Licensor waives any right to
          collect royalties from You for the exercise of the Licensed
          Rights, whether directly or through a collecting society
          under any voluntary or waivable statutory or compulsory
          licensing scheme. In all other cases the Licensor expressly
          reserves any right to collect such royalties.


Section 3 -- License Conditions.

Your exercise of the Licensed Rights is expressly made subject to the
following conditions.

  a. Attribution.

       1. If You Share the Licensed Material (including in modified
          form), You must:

            a. retain the following if it is supplied by the Licensor
               with the Licensed Material:

                 i. identification of the creator(s) of the Licensed
                    Material and any others designated to receive
                    attribution, in any reasonable manner requested by
                    the Licensor (including by pseudonym if
                    designated);

                ii. a copyright notice;

               iii. a notice that refers to this Public License;

                iv. a notice that refers to the disclaimer of
                    warranties;

                 v. a URI or hyperlink to the Licensed Material to the
                    extent reasonably practicable;

            b. indicate if You modified the Licensed Material and
               retain an indication of any previous modifications; and

            c. indicate the Licensed Material is licensed under this
               Public License, and include the text of, or the URI or
               hyperlink to, this Public License.

       2. You may satisfy the conditions in Section 3(a)(1) in any
          reasonable manner based on the medium, means, and context in
          which You Share the Licensed Material. For example, it may be
          reasonable to satisfy the conditions by providing a URI or
          hyperlink to a resource that includes the required
          information.

       3. If requested by the Licensor, You must remove any of the
          information required by Section 3(a)(1)(A) to the extent
          reasonably practicable.

       4. If You Share Adapted Material You produce, the Adapter's
          License You apply must not prevent recipients of the Adapted
          Material from complying with this Public License.


Section 4 -- Sui Generis Database Rights.

Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:

  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
     to extract, reuse, reproduce, and Share all or a substantial
     portion of the contents of the database;

  b. if You include all or a substantial portion of the database
     contents in a database in which You have Sui Generis Database
     Rights, then the database in which You have Sui Generis Database
     Rights (but not its individual contents) is Adapted Material; and

  c. You must comply with the conditions in Section 3(a) if You Share
     all or a substantial portion of the contents of the database.

For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.


Section 5 -- Disclaimer of Warranties and Limitation of Liability.

  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.

  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.

  c. The disclaimer of warranties and limitation of liability provided
     above shall be interpreted in a manner that, to the extent
     possible, most closely approximates an absolute disclaimer and
     waiver of all liability.


Section 6 -- Term and Termination.

  a. This Public License applies for the term of the Copyright and
     Similar Rights licensed here. However, if You fail to comply with
     this Public License, then Your rights under this Public License
     terminate automatically.

  b. Where Your right to use the Licensed Material has terminated under
     Section 6(a), it reinstates:

       1. automatically as of the date the violation is cured, provided
          it is cured within 30 days of Your discovery of the
          violation; or

       2. upon express reinstatement by the Licensor.

     For the avoidance of doubt, this Section 6(b) does not affect any
     right the Licensor may have to seek remedies for Your violations
     of this Public License.

  c. For the avoidance of doubt, the Licensor may also offer the
     Licensed Material under separate terms or conditions or stop
     distributing the Licensed Material at any time; however, doing so
     will not terminate this Public License.

  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
     License.


Section 7 -- Other Terms and Conditions.

  a. The Licensor shall not be bound by any additional or different
     terms or conditions communicated by You unless expressly agreed.

  b. Any arrangements, understandings, or agreements regarding the
     Licensed Material not stated herein are separate from and
     independent of the terms and conditions of this Public License.


Section 8 -- Interpretation.

  a. For the avoidance of doubt, this Public License does not, and
     shall not be interpreted to, reduce, limit, restrict, or impose
     conditions on any use of the Licensed Material that could lawfully
     be made without permission under this Public License.

  b. To the extent possible, if any provision of this Public License is
     deemed unenforceable, it shall be automatically reformed to the
     minimum extent necessary to make it enforceable. If the provision
     cannot be reformed, it shall be severed from this Public License
     without affecting the enforceability of the remaining terms and
     conditions.

  c. No term or condition of this Public License will be waived and no
     failure to comply consented to unless expressly agreed to by the
     Licensor.

  d. Nothing in this Public License constitutes or may be interpreted
     as a limitation upon, or waiver of, any privileges and immunities
     that apply to the Licensor or You, including from the legal
     processes of any jurisdiction or authority.


=======================================================================

Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.

Creative Commons may be contacted at creativecommons.org.


================================================
FILE: MANIFEST.md
================================================
# Pharo wiki manifest

This file will explain the goals of this project and define its boundaries. 

Pharo-wiki is a user maintained wiki on the programming language and development environment Pharo and its ecosystem.

The goals of the project are to provide:
- documentation on parts of Pharo that are not yet or poorly documented;
- a centralized source of information on Pharo;
- pointers to existing documentation;
- tips on possible workflow on Pharo using all the strength of the environment;
- references to external libraries;
- migration guides between differents versions of Pharo.

The project should be easy to contribute to (with a github account the user should just have to edit a file on the github interface to contribute)

To be easy to contribute, this project is written in Markdown and hosted on github. Anyone with a github account can easily provide a Pull Request. (See [Contribution guide](CONTRIBUTION.md))

To achieve these goals, the project is divided into the following sections:

* [Beginners](https://github.com/pharo-open-documentation/pharo-wiki#beginners) - guides for beginners who have just recently discovered Pharo.
* [General](https://github.com/pharo-open-documentation/pharo-wiki#general) - pages describing some of Pharo mechanism and guides on possible workflows.
* [Pharo projects](https://github.com/pharo-open-documentation/pharo-wiki#pharo-projects) - documentation about subprojects contained in the Pharo general distribution.
* [External projects](https://github.com/pharo-open-documentation/pharo-wiki#external-projects) - information about external projects. Most of the pages give some examples to give an idea on how those project work and offer comparisons between multiple projects around the same theme.
* [Migration guidelines](https://github.com/pharo-open-documentation/pharo-wiki#migration-guidelines) - migration guides between different versions of Pharo.
* [External ressources](https://github.com/pharo-open-documentation/pharo-wiki#external-ressources) - links to ressources not maintained by the wiki community but interesting to check-out.

As long as they fit the goals of the wiki, the entries of this project can be:
- documentation
- tutorials
- guides
- tips and tricks

If you want to contribute but you are not sure your contribution fits the goals of the project, do not hesitate to open an issue to ask the maintainers for advice.

If you wish to contribute, you should read the [contribution guide](CONTRIBUTION.md).


================================================
FILE: Migration/MigrationToPharo7.md
================================================
# Migration from Pharo 6.1 to Pharo 7.0 guideline

## Pharo 7 file streams guideline

Since version 5, Pharo provides a new file streams API that deprecates the one based on classes 
like `FileStream` or `MultiByteBinaryOrTextStream`. In Pharo 7 this deprecated API was removed from the kernel.

### Key points

- use file references as entry points to file streams
- do not use the `FileStream` class
- `'file.txt' asFileReference readStream` and similar methods now return an instance of `ZnCharacterReadStream`
instead of `MultiByteFileStream`
- `'file.txt' asFileReference writeStream` and similar methods now return an instance of `ZnCharacterWriteStream` 
instead of `MultiByteFileStream`
- the new API has a clearer separation between binary and text files

### Code conversion

This section shows the most common examples of file streams. For simplicity, errors are not handled.

#### Force creation of a new file and write a UTF-8 text

##### obsolete code
```smalltalk
FileStream forceNewFileNamed: '1.txt' do: [ :stream | stream nextPutAll: 'a ≠ b' ].
```

##### new code
```smalltalk
'1.txt' asFileReference ensureDelete; 
	writeStreamDo: [ :stream | stream nextPutAll: 'a ≠ b' ].
```

#### Read UTF-8 text from an existing file

##### obsolete code
```smalltalk
FileStream readOnlyFileNamed: '1.txt' do: [ :stream | 
	stream upToEnd ].
```

##### new code
```smalltalk
'1.txt' asFileReference readStreamDo: [ :stream | 
	stream upToEnd ].
```

#### Get all content of existing UTF-8 file

##### obsolete code
```smalltalk
(FileStream readOnlyFileNamed: '1.txt') contentsOfEntireFile.
  ```

##### new code
```smalltalk
'1.txt' asFileReference readStream upToEnd.
```

#### Force creation of a new file and write binary data into it

##### obsolete code
```smalltalk
(FileStream forceNewFileNamed: '1.bin') 
	binary;
	nextPutAll: #[1 2 3].
```

##### new code
```smalltalk
'1.bin' asFileReference ensureDelete; 
	binaryWriteStreamDo: [ :stream | stream nextPutAll: #[1 2 3] ].
```

#### Read binary data from an existing file

##### obsolete code
```smalltalk
(FileStream readOnlyFileNamed: '1.bin') binary; contentsOfEntireFile.
```

##### new code
```smalltalk
'1.bin' asFileReference binaryReadStream upToEnd.
```

#### Force creation of a new file with a different encoding

##### obsolete code
```smalltalk
FileStream forceNewFileNamed: '2.txt' do: [ :stream | 
	stream converter: (TextConverter newForEncoding: 'cp-1250').
	stream nextPutAll: 'Příliš žluťoučký kůň úpěl ďábelské ódy.' ].
```

##### new code
```smalltalk
('2.txt' asFileReference) ensureDelete;
	writeStreamEncoded: 'cp-1250' do: [ :stream |
		stream nextPutAll: 'Příliš žluťoučký kůň úpěl ďábelské ódy.' ].
```

#### Read encoded text from an existing file

##### obsolete code
```smalltalk
FileStream readOnlyFileNamed: '2.txt' do: [ :stream | 
	stream converter: (TextConverter newForEncoding: 'cp-1250').
	stream upToEnd ].

```

##### new code
```smalltalk
('2.txt' asFileReference)
	readStreamEncoded: 'cp-1250' do: [ :stream |
		stream upToEnd ].
```

#### Write a UTF-8 text to STDOUT

##### obsolete code
```smalltalk
FileStream stdout nextPutAll: 'a ≠ b'; lf.
```

##### new code
```smalltalk
(ZnCharacterWriteStream on: Stdio stdout)
	nextPutAll: 'a ≠ b'; lf;
	flush.
```

#### Write CP-1250 encoded text to STDOUT

##### obsolete code
```smalltalk
FileStream stdout 
	converter: (TextConverter newForEncoding: 'cp-1250');
	nextPutAll: 'Příliš žluťoučký kůň úpěl ďábelské ódy.'; lf.
```

##### new code
```smalltalk
(ZnCharacterWriteStream on: Stdio stdout encoding: 'cp1250')
	nextPutAll: 'Příliš žluťoučký kůň úpěl ďábelské ódy.'; lf;
	flush.
```

#### Read a UTF-8 text from STDIN

**CAUTION:** The following code will block your VM until input on STDIN is provided!

##### obsolete code
```smalltalk
FileStream stdin upTo: Character lf.
```

##### new code
```smalltalk
(ZnCharacterReadStream on: Stdio stdin) upTo: Character lf.
```

#### Write binary data to STDOUT

##### obsolete code
```smalltalk
FileStream stdout 
	binary
	nextPutAll: #[80 104 97 114 111 10 ].
```

##### new code
```smalltalk
Stdio stdout 
	nextPutAll: #[80 104 97 114 111 10 ].
```

#### Read binary data from STDIN

**CAUTION:** The following code will block your VM until input on STDIN is provided!

##### obsolete code
```smalltalk
FileStream stdin binary upTo: 10.
```

##### new code
```smalltalk
Stdio stdin upTo: 10.
```

### Positionable streams

The message `#position:` always works at the binary level, not at the character level.

```smalltalk
'1.txt' asFileReference readStreamDo: [ :stream | 
	stream position: 4.
	stream upToEnd ].
```

This will lead to an error (ZnInvalidUTF8: Illegal leading byte for utf-8 encoding) in case of 
the file created above, because we set the position into the middle of a UTF-8 encoded character.
To be safe, you need to read the file from the beginning.

```smalltalk
'1.txt' asFileReference readStreamDo: [ :stream |
	3 timesRepeat: [ stream next ].
	stream upToEnd.].
```

#### Buffering

The `MultiByteFileStream` was buffered. If you create a stream using the expression

```smalltalk
'file.txt' asFileReference readStream.
```

then the `ZnCharacterReadStream` is not created directly on top of the stream but on top of a buffered stream 
that uses the file stream internally. 

If you create a `ZnCharacterReadStream` directly on the file stream, then the characters from the file are read 
one by one which may be about **ten times slower**!

```smalltalk
ZnCharacterReadStream on: (File openForReadFileNamed: 'file.txt').
```

#### Binary streams do not understand #<< message anymore

Binary streams used to understand `#<<` message in the past, but not anymore. One should either use `#next:` or `#nextPutAll:`.


================================================
FILE: PharoProjects/Announcer.md
================================================
# Announcer
`Announcer` and `Announcement` classes provide an implementation of the [observer design pattern](https://en.wikipedia.org/wiki/Observer_pattern) in Pharo.
As written on the wikipedia page, it aims to address the following problems:

- A one-to-many dependency between objects should be defined without making the objects tightly coupled.
- It should be ensured that, when one object changes state, an open-ended number of dependent objects are updated automatically.
- It should be possible that one object can notify an open-ended number of other objects.

This page provide a quick tutorial to get started with them.

- [Getting started](#getting-started)
- [Defining new kind of Announcement](#defining-new-kind-of-announcement)
- [Using announcer for your subject object](#using-announcer-for-your-subject-object)

## Getting started
The `Announcer` class implements a mechanism to:
1. Allow objects (the observers) to subscribe to announcements
2. Manage objects subscriptions
3. Allow the object holding the announcer (the subject) to announce events

For example, there is an announcer available to let objects listen to announcements (events) concerning the system: `SystemAnnouncer uniqueInstance`.
Such announcements include:
- `ClassAdded`
- `ClassRemoved`
- `MethodModified`
- etc.

If one wants to be notified when a class is removed, it is possible to subscribe an object to this specific announcement as follow.

First, let's create the method `#whenClassAdded:` for the object that will listen to `ClassAdded` announcement.
This method will be the hook called when such announcement has been announced.
It takes the announcement sent by the subject as parameter.

```Smalltalk
MyObjectListeningToClassAdded>>#whenClassAdded: aClassAdded
  Transcript
    show: aClassAdded classAffected name;
    show: ' has been added.';
    cr
```

Then, we subscribe an instance of our object to the announcer.
When doing that, it is needed to specify
1. Which kind of announcements (its class) our object listen to.
2. Which object listen to this kind of announcements.
3. Which method to call when the annoncement is sent.

The previous step can be achieved as follow:

```Smalltalk
SystemAnnouncer uniqueInstance
  when: ClassAdded send: #whenClassAdded: to: instanceOfMyObjectListeningToClassAdded
```

> Note: the SystemAnnouncer is a bit special because it is a subclass of `Announcer`.
> Usually, when creating you own announcer, you do not subclass `Announcer` but rather use it directly by storing an instance in a dedicated instance variable (see Section "[Using announcer for your subject object](#using-announcer-for-your-subject-object)").

Once the code above has been executed, a message is printed in the Transcript each time a class has been added.
To unsubscribe an object from an announcer, simply call `#unsubscribe:` method on the announcer.

```Smalltalk
SystemAnnouncer uniqueInstance
  unsubscribe: instanceOfMyObjectListeningToClassAdded
```

## Defining new kind of Announcement
Creating a new kind of announcement to fit your needs is easy, just subclass `Announcement` class.
For example, let's say you have an object that has a color. You want to allow observers to listen to color changes of the object.
To do that, let's create a `ColorChangeAnnouncement` class:

```Smalltalk
Announcement subclass: #ColorChangeAnnouncement
	slots: { #newColor }
	classVariables: {  }
	package: 'MyPackage'
```

Your new kind of announcement aims to hold all the information you need.
In our example, `ColorChangeAnnouncement` hold the new color in `#newColor` instance variable.

## Using announcer for your subject object
The common pattern to use an `Announcer` in your subject object is to:
1. Create an `#announcer` instance variable which will contain the instance of `Announcer`.
2. Create an accessor method for `#announcer` instance variable that use lazy-initialization (so no announcer is created if no announcement is sent and no one wants to subscribe to events of the subject).
3. The subject object send announcements through its announcer.

As an example, let's implement the object changing its color discussed in previous section"

```Smalltalk
Object subclass: #MyObjectChangeColor
	slots: { #announcer. #color }
	classVariables: {  }
	package: 'MyPackage'
```

Then we create the accessor for `#announcer` with lazy-initialisation.

```Smalltalk
MyObjectChangeColor>>#announcer
  ^ announcer ifNil: [ announcer := Announcer new ]
```

And when the color of the object is updated, we announce it:

```Smalltalk
MyObjectChangeColor>>#color: aColor
  color := aColor.
  self announcer
    announce: (ColorChangeAnnouncement new
                newColor: aColor;
                yourself)
```


================================================
FILE: PharoProjects/Cursor.md
================================================
# Cursor

The `Cursor` class in Pharo manages the display of the cursor on the screen.

It is possible to change the way it looks and we will explain how here.

To select the cursor you want you can check the class side of the `Cursor` class, in "constants" protocol.

The common way to change the look of the cursor is to change it for the execution of a block and then set it back to the original cursor. To do that you can use the `showWhile:` method.

```Smalltalk
Cursor wait showWhile: [ 3 second wait ]
```

It might be needed to have full control on the cursor without using a block. To do that Morph implements methods to help with the management of cursors via the hand morph. In the following code, `self` can be any object (`#currentHand` is defined on Object).

```Smalltalk
self currentHand showTemporaryCursor: Cursor wait. 
self flag: #doSomethingHere.
self currentHand showTemporaryCursor: nil. "Reset the cursor to the previous one"
```


================================================
FILE: PharoProjects/DynamicVariables.md
================================================
# Dynamic variables

Pharo contains a system of dynamic variables which are global variables whose value can be changed during the execution of a process.

> Be careful when you use these variables. They should not be used just as a global variable to make access to it easier in the code.

A logger system is good example of the usefulness of dynamic variables. In such a system, we can imagine that we have a default logger that will be used to record logs. However, in some specific cases we want to use a custom logger. In that case a dynamic variable can do the work. If you wish to see it at work you can check this [logger project using it](https://github.com/jecisc/TinyLogger).

## Create a new dynamic variable

To create a new dynamic variable you just need to create a new subclass of `DynamicVariable`:

```Smalltalk
DynamicVariable subclass: #MyVariable
	slots: {  }
	classVariables: {  }
	package: 'MyProject'
```

## Add a default value

It is possible to assign a default value to your dynamic variable. To do so, you need to add a `default` method.

```Smalltalk
MyVariable>>default
	^ MyDefaultObject
 ```
 
## Use your dynamic variable

To use your variable, just send the `value` message to it. If you have no default value, do not forget to manage the case where it can be nil if it can happen.

```Smalltalk
MyVariable value doSomething
```

## Change the value of the variable in a process

If you need to change the value of the variable for the execution of a specific process, just use the `value:during:` message.

```Smalltalk
MyVariable value: MyNewObject during: [
	self doAnActionUsingTheVariable.
]
```

## Example

Here is the way dynamic variables are used in the `TinyLogger` project cited above.

```Smalltalk
DynamicVariable subclass: #TinyCurrentLogger
	slots: {  }
	classVariables: {  }
	package: 'TinyLogger-Core'
```

```Smalltalk
TinyCurrentLogger>>default
	^ TinyLogger default
```

```Smalltalk
Object>>record: aString
	TinyCurrentLogger value record: aString
```

```Smalltalk
Object>>execute: aBlock recordedAs: aString
	TinyCurrentLogger value execute: aBlock recordedAs: aString
```

```Smalltalk
	TinyCurrentLogger value: (TinyLogger new addTranscriptLogger; yourself) during: [ 
		'test' record.
		TinyCurrentLogger value record: 'Test2'
	]
```




================================================
FILE: PharoProjects/Metalinks.md
================================================
# Metalinks

> **TODO**


================================================
FILE: PharoProjects/Numbers.md
================================================
# Numbers
This page provides some hints for using Pharo's numbers. For more detailled information, check [Pharo by Example book](http://books.pharo.org/pharo-by-example).


## Numbers are not primitive
As written in [Pharo by Example book](http://books.pharo.org/pharo-by-example),

> Remarkably, numbers in Smalltalk are not primitive data values but true objects. Of course numbers are implemented efficiently in the virtual machine, but the Number hierarchy is as perfectly accessible and extensible as any other portion of the Smalltalk class hierarchy. - [Pharo by Example](http://books.pharo.org/pharo-by-example), Chapter 8 Section 2

Which is an interesting feature because it means that extension methods can be added to create objects holding a quantity. This is what is done for `Duration`s:

```Smalltalk
5 seconds. "0:00:00:05"
```

`#seconds` method creates a new instance of `Duration` representing the number second required.

## Scaled decimals
Scaled decimals allow one to model rationals. That is to say numbers with a fixed number of decimals. They are handy when dealing with money for example. It is possible to create a ScaledDecimal from its litteral form using the `s` notation: `1.45s2` which will store 1.45 with 2 digits precision in decimals.

## Special numbers
- Infinity: `Float infinity`
- Negative infinity: `Float negativeInfinity`
- Not a number: `Float nan`
- Pi, 2\*Pi, 3\*Pi: `Float pi. Float twoPi. Float threePi`
- Euler's number: `Float e`

## Parse number
The class-side methods `#readFrom:` and `#readFrom:base:` of `Number` class allow one to parse a number from a `String`. Here are some examples:

```Smalltalk
Number readFrom: '10'. "10"
Number readFrom: '10' base: 2. "2"
Number readFrom: '1.0'. "1.0"
```

A specific subclass of `Number` can be used to ensure that the object created by the parser is of a specific kind:

```Smalltalk
Integer readFrom: '10'. "10"
Float readFrom: '1.0'. "1.0"
```


================================================
FILE: PharoProjects/OS.md
================================================
# Basic interactions with the OS
This page describes basic interactions with the OS. The code snippet below should be working on all OS and are built-in: you do not need to install an external project to use them.

- [Execute shell command](#execute-shell-command)
- [Write environment variable](#write-environment-variable)
- [Read environment variable](#read-environment-variable)

## Execute shell command
The following code execute a shell command and returns an integer which is the return code of the executed command.
If the return code is `0`, the execution of the command is successful. Else, the integer returned is the error code generated by the shell command.

```Smalltalk
LibC uniqueInstance
	system: 'echo "foo" >> /tmp/foo.txt'
```

To retrieve the output of a command directly in Pharo, use `#resultOfCommand:`

```Smalltalk
LibC uniqueInstance
	resultOfCommand: 'echo "foo"'. "'foo
'"
```

## Write environment variable
The environment behaves similarly to a dictionary when it comes to write a variable.

```Smalltalk
Smalltalk os environment at: 'FOO' put: 'bar'.
Smalltalk os environment at: 'FOO' ifAbsentPut: 'bar'
```

> Note: Before Pharo 7, `#setEnv:value:` message was used. This message is part of the low-level API and should not be used directly.

## Read environment variable
As for writing a variable, environment provide an API similar to `Dictionary` to read a variable.

```Smalltalk
Smalltalk os environment at: 'FOO'.
Smalltalk os environment at: 'FOO' ifAbsent: [ 'Nope :-(' ].
Smalltalk os environment at: 'FOO' ifPresent: [ :value | "Do something interesting." ]
```

> Note: Before Pharo 7, #getEnv: message was used. This message is now deprecated and should not be used.


================================================
FILE: PharoProjects/ObjectsSerialization.md
================================================
# Objects serialization support
To be done.

## STON
-> [doc](https://github.com/svenvc/ston/blob/master/ston-paper.md)

## Fuel
-> [doc]()

## STON v.s. Fuel

|Property                                            |STON                |Fuel                |
|----------------------------------------------------|--------------------|--------------------|
|Human-readable                                      | :white_check_mark: | :x:                |
|Built-in                                            | :white_check_mark: | :white_check_mark: |
|Works between different major Pharo versions        | :white_check_mark: | :x:*               |
|Does not require configuration on seralized objects | :x:                | :white_check_mark: |

> *It might work but it is not likely. If a fix was done on Fuel during Pharo development (which is likely), it might make your `.fuel` files unreadable by Pharo. STON is more stable from this perspective.


================================================
FILE: PharoProjects/RichText.md
================================================
# Rich text in Pharo

`Text` object models rich text. That is to say text that can be stylised with **bold**, *italics*, colors, different fonts and a few other things. The class `Text` is one of the really ancient classes in smalltalk.

- [Quickstart](#quickstart)
- [TextEmphasis](#textemphasis)
- [Colors](#colors)
- [Different fonts](#different-fonts)
- [Clickable text](#clickable-text)
- [Inline images](#inline-images)

## Quickstart
Here is a quick example illustrating how attributes can be added to `Text` object to create rich text in Pharo:

```Smalltalk
text := 'Hello World!' asText.
text
	addAttribute: TextEmphasis italic from: 7 to: 11;
	addAttribute: TextEmphasis struckOut from: 7 to: 11;
	addAttribute: (TextColor color: Color red) from: 7 to: 11;
	addAttribute: (TextColor color: Color green) from: 12 to: 12.
```

## TextEmphasis
The class `TextEmphasis` defines a set of simple (no font change) changes you can do. See the class side of `TextEmphasis` for the supported styles of emphasis.

It is possible to overlap the different emphasis styles:

```Smalltalk
text := 'Hello World!' asText.
text
	addAttribute: TextEmphasis italic from: 7 to: 11;
	addAttribute: TextEmphasis struckOut from: 7 to: 11.
```

## Colors
Colored text is done as shown below. Examine the class `Color` for other colors.

```Smalltalk
text := 'Hello World!' asText.
text
	addAttribute: (TextColor color: Color red) from: 7 to: 11;
	addAttribute: (TextColor color: Color green) from: 12 to: 12.
```

## Different fonts
Loading and managing fonts is an issue in itself.

You can see which fonts you have available in your image using `StrikeFont actualFamilyNames`.

Assume you have a font named: `Bitmap Source Sans Pro` (was the case on Macbook Pro, Pharo 8, fall 2019). 

You need to turn the font into a text attribute:

```Smalltalk
largeAttribute := TextFontReference
		toFont:
			(StrikeFont
				familyName: 'Bitmap Source Sans Pro'
				pointSize: 20).
'My larger text' asText addAttribute: largeAttribute from: 4 to: 10.
```

This should give you 'My larger text' with 'larger' being in font size 20 and in the 'Bitmap Source Sans Pro' font.

## Clickable text
It is possible to make text do stuff when clicked. This is obviously a huge area. One simple example is:

```Smalltalk
textAction := TextAction new 
	actOnClickBlock: [ 
		Transcript nextPutAll: 'action clicked';cr;endEntry
		].
'My action text' asText addAttribute: textAction from: 4 to: 10.
```

## Inline images
It is possible to insert images into text. It is done using a `TextAnchor` attribute which can only be put on the text obtained using the expression `(String value: 1) asText`. The following example illustrates this:

```Smalltalk
anchoredImage := 
	(String value: 1) asText addAttribute: 
		(TextAnchor new anchoredMorph: PolymorphSystemSettings pharoLogoForm ).

('Line before image\' withCRs asText), 
anchoredImage,  
('\Line afterimage' withCRs asText).
```

There are further examples in the class comment of `TextAnchor`.

> Note:
> The inline images relies on the morphic system. Not all morphs seem to be able to be inlined in text in Pharo.
> 
> In addition, you will most likely get the best results if you put images larger than the font size on a line by themself. The class comment of `TextAnchor` has an example of inlining a small icon.


================================================
FILE: PharoProjects/WebBrowser.md
================================================
# Web browser

*WebBrowser* is a project included since Pharo 7. The goal of the project is to offer to the user the possibility to open a link directly into the default browser of the computer.

It currently supports:
- Most linux 32 and 64bits
- OSX 32 and 64bits
- Windows 32bits

To use it you just need to call:

```Smalltalk
WebBrowser openOn: 'https://pharo.org'
```


================================================
FILE: PharoVirtualMachine/pharo-vm-map.md
================================================

# Introduction

## design principles behind smalltalk
https://www.cs.virginia.edu/~evans/cs655/readings/smalltalk.html

**"*Personal Mastery*: If a system is to serve the creative spirit, it must be entirely comprehensible to a single individual. "**

The history of opensmalltalk/pharo virtual machine started a long time ago, with Smalltalk-80, and then in the squeak virtual machine, now opensmalltalk.

http://files.squeak.org/docs/OOPSLA.Squeak.html

"Squeak is an open, highly-portable Smalltalk implementation whose virtual machine is written entirely in Smalltalk, making it easy to debug, analyze, and change. To achieve practical performance, a translator produces an equivalent C program whose performance is comparable to commercial Smalltalks."

## overview
Two major components of the Smalltalk-80 system can be distinguished: the virtual image and the virtual machine.

1. The virtual image consists of all of the objects in the system, including Smalltalk source code objects, compiler objects, and bytecode compiled method objects. It is platform independent.
1. The virtual machine is the engine that runs the image. It consists of a machine language (or microcode or bytecode) routines that give dynamics to the objects in the virtual image. It is a platform dependent machine code executable that can be decomposed into: 
    * *Bytecode execution engine* - to interpret or JIT (Just In Time) compile each bytecode into machine code and execute it;  
    * *Object engine* - to provide memory management of objects;   
    * *Primitives* - to provide AOT (Ahead Of Time) compiled machine code for accelerated execution and interface to platform dependent operating system routines."


The system implementer's task is to create a virtual machine. A virtual image can then be loaded into the virtual machine and the pharo system becomes an interactive entity.

The various link of the opensmalltalk/pharo VM implementation given in this chapter is organized in a top-down fashion, starting with the source methods written by programmers. These methods are translated by a *compiler* into sequences of instructions called bytecodes. The bytecodes produced by the compiler are instructions for an *interpreter*. Below the interpreter in the implementation is an *object memory* that stores the objects that make up the virtual image.





Main lecture: Smalltalk - 80. The language and its implementation:
[http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook.pdf](http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook.pdf)

Especially, the part that are related to the VM: pages 541 to pages 691
A web format can be found here:
http://www.mirandabanda.org/bluebook/

A tour of the squeak object engine show a good overview, but is a bit more outdated:
http://stephane.ducasse.free.fr/FreeBooks/CollectiveNBlueBook/Rowledge-Final.pdf

Bytecode and Virtual Machines:
http://scg.unibe.ch/download/lectures/cc2011/09BytecodeVirtualMachines.pptx.pdf

An overview of all the the changes brough to opensmalltalk/pharo VM:
https://www.researchgate.net/publication/328509577_Two_Decades_of_Smalltalk_VM_Development_Live_VM_Development_through_Simulation_Tools

## set up
http://forum.world.st/ANN-Pharo-Headless-Beta-Actually-what-is-between-Alpha-and-Beta-td5102089.html

headless VM: https://github.com/pharo-project/opensmalltalk-vm located in the headless branch.

You'll find instruction on how to build it on the github page. In addition, you'll get an image with VMMaker loaded so you can study the code of the VM.

Tips on debugging the VM:
* https://pharoweekly.wordpress.com/2019/08/28/pharo-headless-linux-vm-debugging/
* https://clementbera.wordpress.com/2016/05/30/simulating-the-cog-vm/


# Compiler, bytecodes and compiled method
## introduction
[https://marianopeck.wordpress.com/2011/04/30/smalltalk-reflective-model/](https://marianopeck.wordpress.com/2011/04/30/smalltalk-reflective-model/)
## compiler - Opal
Source methods written by programmers are represented in the system as instances of *String*. The Strings contain sequences of characters that conform to the pharo syntax.

Source methods are translated by the system's *compiler* into sequences of instructions. The instructions are called bytecodes.

* Towards a flexible Pharo Compiler: https://hal.inria.fr/hal-00862411/document
* https://rmod.inria.fr/archives/events/2011DIS/Slides/Opal/OpalCompiler.pdf
* https://clementbera.wordpress.com/2013/03/22/toward-a-zero-bugs-interpreter-compiler/
* https://clementbera.wordpress.com/2013/05/28/modular-compilation-with-opal/

### Example of live compiling
* http://forum.world.st/Squeak-Compiler-evaluate-3-4-Pharo-equivalent-td5086475.html
* http://forum.world.st/evaluate-with-bindings-td5071919.html

## bytecode:
The original smalltalk interpreter understands 256 bytecode instructions that fall into five categories: pushes, stores, sends, returns, and jumps. Since more than 256 instructions for the interpreter are needed, some of the bytecodes take extensions. An extension is one or two bytes following the bytecode that further specify the instruction. An extension is not an instruction on its own, it is only a part of an instruction. 

* [https://marianopeck.wordpress.com/2011/05/21/introduction-to-smalltalk-bytecodes/](https://marianopeck.wordpress.com/2011/05/21/introduction-to-smalltalk-bytecodes/)
* https://clementbera.wordpress.com/2013/04/21/byte-code-to-source-code-mappin/
* https://clementbera.wordpress.com/2013/09/23/squeakv3plusclosure-bytecode-set/
* A bytecode set for adaptive optimizations: https://hal.inria.fr/hal-01088801/document

## compiled method:
The compiler creates an instance of *CompiledMethod* to hold the bytecode translation of a source method. 

* [https://marianopeck.wordpress.com/2011/05/14/playing-with-compiledmethod/](https://marianopeck.wordpress.com/2011/05/14/playing-with-compiledmethod/)
* [https://marianopeck.wordpress.com/2011/06/03/primitives-pragmas-literals-and-their-relation-to-compiledmethods/](https://marianopeck.wordpress.com/2011/06/03/primitives-pragmas-literals-and-their-relation-to-compiledmethods/)
* https://clementbera.wordpress.com/2013/07/29/smalltalk-method-and-block-models/
* http://www.mirandabanda.org/cogblog/2008/06/17/bluebook-compiledmethods-having-our-cake-and-eating-it-too/
* [https://marianopeck.wordpress.com/2011/07/06/named-primitives/](https://marianopeck.wordpress.com/2011/07/06/named-primitives/)

## class format:
[https://marianopeck.wordpress.com/2011/05/07/class-formats-and-compiledmethod-uniqueness/](https://marianopeck.wordpress.com/2011/05/07/class-formats-and-compiledmethod-uniqueness/)

# stack interperter
The original smalltalk system wat a stack-oriented interpreter. A big part of the system still contain its source code, which is enhanced with Just In Time  (JIT) in recent version.

The Smalltalk-80 interpreter executes the bytecode instructions found in *CompiledMethods*. The interpreter uses five pieces of information and repeatedly performs a three-step cycle. 

More information: 
http://www.mirandabanda.org/bluebook/bluebook_chapter26.html#TheInterpreter26

Understand how a call stack interperter is working:
https://files.pharo.org/books-pdfs/booklet-CallStack/2018-01-23-CallStack.pdf

Understand how a simple system may work:
http://books.pharo.org/booklet-ReflectiveCore/pdf/2018-03-05-ReflectiveKernel-spiral.pdf


## context
The interpreter uses *contexts* to represent the state of its execution of *CompiledMethods* and *blocks*. A context can be a *MethodContext* or a *BlockContext*. A MethodContext represents the execution of a CompiledMethod that was invoked by a message.

* http://www.mirandabanda.org/bluebook/bluebook_chapter26.html#Contexts26

* http://www.mirandabanda.org/bluebook/bluebook_chapter27.html#Contexts27

### in Opensmalltalk/Pharo
http://www.mirandabanda.org/cogblog/2009/01/14/under-cover-contexts-and-the-big-frame-up/

## block closure
### In the original smalltalk-80 system:
http://www.mirandabanda.org/bluebook/bluebook_chapter26.html#BlockContexts26


### In Opensmalltalk/pharo
* http://www.mirandabanda.org/cogblog/2008/06/07/closures-part-i/
* http://www.mirandabanda.org/cogblog/2008/07/22/closures-part-ii-the-bytecodes/
* http://www.mirandabanda.org/cogblog/2008/07/24/closures-part-iii-the-compiler/

* https://clementbera.wordpress.com/2016/06/27/fullblockclosure-design/

# object memory
The object memory provides the interpreter with an interface to the objects that make up the pharo virtual image. Each object is associated with a unique identifier called its object pointer. The object memory and interpreter communicate about objects with object pointers.

The object memory associates each object pointer with a set of other object pointers. Every object pointer is associated with the object pointer of a class. If an object has instance variables, its object pointer is also associated with the object pointers of their values. The individual instance variables are referred to by zero-relative integer indices. The value of an instance variable can be changed, but the class associated with an object cannot be changed. The object memory provides the following five fundamental functions to the interpreter.
http://www.mirandabanda.org/bluebook/bluebook_chapter26.html#TheObjectMemory26

### in Opensmalltalk/Pharo

* [https://marianopeck.wordpress.com/2011/10/26/memory-addresses-and-immediate-objects/](https://marianopeck.wordpress.com/2011/10/26/memory-addresses-and-immediate-objects/)
* http://www.mirandabanda.org/cogblog/2013/09/05/a-spur-gear-for-cog/
* https://clementbera.wordpress.com/2014/01/16/spurs-new-object-format/
* https://clementbera.wordpress.com/2014/02/06/7-points-summary-of-the-spur-memory-manager/


# beyond smalltalk-80 original VM - JIT
## Just In Time - JIT
* http://www.mirandabanda.org/cogblog/2011/03/01/build-me-a-jit-as-fast-as-you-can/
* http://www.mirandabanda.org/cogblog/2011/03/04/an-arranged-marriage/

## memory compactor and garbage collection
* https://clementbera.wordpress.com/2018/06/07/free-chunk-management-in-the-cog-vm/
* https://clementbera.wordpress.com/2017/03/12/tuning-the-pharo-garbage-collector/

### Specific to Pharo
https://github.com/SquareBracketAssociates/Booklet-PharoVirtualMachine

## other
Sub-method, partial behavioral reflection with Reflectivity: Looking back on 10 years of use
https://programming-journal.org/2020/4/5/

Debugging the VM through the simulator (video)
* https://clementbera.wordpress.com/2018/03/07/sista-vm-screencast/

* http://www.mirandabanda.org/cogblog/2008/11/14/mechanised-modifications-and-miscellaneous-measurements/

## multi-user transactional image
magma object representation by Chris Muller. 
* https://wiki.squeak.org/squeak/2665.

# UFFI
* https://users.dcc.uchile.cl/~rsalgado/uffi-fourth-draft.pdf
* http://books.pharo.org/booklet-uffi/pdf/2020-02-12-uFFI-V1.0.1

Pharo threaded FFI
https://github.com/pharo-project/threadedFFI-Plugin


# parameters of the virtual machine

found in
```smalltalk
VirtualMachine >> parameterAt: parameterIndex

	"parameterIndex is a positive integer corresponding to one of the VM's internal
	parameter/metric registers.  Answer with the current value of that register.
	Fail if parameterIndex has no corresponding register.
	VM parameters are numbered as follows:
	1	end (v3)/size(Spur) of old-space (0-based, read-only)
	2	end (v3)/size(Spur) of young/new-space (read-only)
	3	end (v3)/size(Spur) of heap (read-only)
	4	nil (was allocationCount (read-only))
	5	nil (was allocations between GCs (read-write)
	6	survivor count tenuring threshold (read-write)
	7	full GCs since startup (read-only)
	8	total milliseconds in full GCs since startup (read-only)
	9	incremental GCs (SqueakV3) or scavenges (Spur) since startup (read-only)
	10	total milliseconds in incremental GCs (SqueakV3) or scavenges (Spur) since startup (read-only)
	11	tenures of surving objects since startup (read-only)
	12-20 were specific to ikp's JITTER VM, now 12-19 are open for use
	20	utc microseconds at VM start-up (actually at time initialization, which precedes image load).
	21	root table size (read-only)
	22	root table overflows since startup (read-only)
	23	bytes of extra memory to reserve for VM buffers, plugins, etc (stored
	in image file header).
	24	memory threshold above which shrinking object memory (rw)
	25	memory headroom when growing object memory (rw)
	26	interruptChecksEveryNms - force an ioProcessEvents every N milliseconds	(rw) 27	number of times mark loop iterated for current IGC/FGC (read-only)	includes ALL marking
	28	number of times sweep loop iterated for current IGC/FGC (read-only)
	29	number of times make forward loop iterated for current IGC/FGC	(read-only) 30	number of times compact move loop iterated for current	IGC/FGC (read-only)
	31	number of grow memory requests (read-only)
	32	number of shrink memory requests (read-only)
	33	number of root table entries used for current IGC/FGC (read-only)
	34	number of allocations done before current IGC/FGC (read-only)
	35	number of survivor objects after current IGC/FGC (read-only)
	36	millisecond clock when current IGC/FGC completed (read-only)
	37	number of marked objects for Roots of the world, not including Root	Table entries for current IGC/FGC (read-only)
	38	milliseconds taken by current IGC (read-only)
	39	Number of finalization signals for Weak Objects pending when current	IGC/FGC completed (read-only)
	40	BytesPerOop for this image
	41	imageFormatVersion for the VM
	42	number of stack pages in use
	43	desired number of stack pages (stored in image file header, max 65535)
	44	size of eden, in bytes
	45	desired size of eden, in bytes (stored in image file header)
	46	machine code zone size, in bytes (Cog only; otherwise nil)
	47	desired machine code zone size (stored in image file header; Cog only;	otherwise nil)
	48	various header flags. See getCogVMFlags.
	49	max size the image promises to grow the external semaphore table to (0	sets to default, which is 256 as of writing)
	50-51 nil; reserved for VM parameters that persist in the image (such as	eden above)
	52	root table capacity
	53	number of segments (Spur only; otherwise nil)
	54	total size of free old space (Spur only, otherwise nil)
	55	ratio of growth and image size at or above which a GC will be performed	post scavenge
	56	number of process switches since startup (read-only)
	57	number of ioProcessEvents calls since startup (read-only)
	58	number of ForceInterruptCheck calls since startup (read-only)
	59	number of check event calls since startup (read-only)
	60	number of stack page overflows since startup (read-only)
	61	number of stack page divorces since startup (read-only)	62	compiled code compactions since startup (read-only; Cog only; otherwise nil)
	63	total milliseconds in compiled code compactions since startup	(read-only; Cog only; otherwise nil)
	64	the number of methods that currently have jitted machine-code
	65	whether the VM supports a certain feature, MULTIPLE_BYTECODE_SETS is bit 0, IMMTABILITY is bit 1
	66	the byte size of a stack page
	67	the max allowed size of old space (Spur only; nil otherwise; 0 implies	no limit except that of the underlying platform)
	68	the average number of live stack pages when scanned by GC (at	scavenge/gc/become et al)
	69	the maximum number of live stack pages when scanned by GC (at	scavenge/gc/become et al)
	70	the vmProxyMajorVersion (the interpreterProxy VM_MAJOR_VERSION)
	71	the vmProxyMinorVersion (the interpreterProxy VM_MINOR_VERSION)"
```


================================================
FILE: README.md
================================================
# Pharo wiki

Wiki for the [Pharo](https://pharo.org/features) programming language and development environment.

The goals of the wiki are explained in the [Manifest](MANIFEST.md) and contribution guidelines in the [Contribution guide](CONTRIBUTION.md).

> Looking for a list of awesome projects? Check-out [awesome-pharo](https://github.com/pharo-open-documentation/awesome-pharo), a curated list of awesome Pharo projects.

- [Pharo wiki](#pharo-wiki)
  * [Beginners](#beginners)
  * [General](#general)
    + [Infrastructure](#infrastructure)
    + [Pharo Language](#pharo-language)
    + [Pharo Tooling](#pharo-tooling)
  * [Pharo projects](#pharo-projects)
  * [Pharo and OpenSmalltalk Virtual Machine](#pharo-and-opensmalltalk-virtual-machine)
  * [External projects](#external-projects)
    + [Data exchange](#data-exchange)
    + [Data structures](#data-structures)
  * [Migration guidelines](#migration-guidelines)
  * [External resources](#external-resources)

## Beginners

- [Setting up a new project](General/SettingUpANewProject.md) ![Unfinished](https://img.shields.io/badge/Progress-Unfinished-yellow.svg?style=flat)
- [Things beginners must learn](General/MustKnowForBeginners.md)
- [Interesting things to know for beginners](General/InterestingsToKnowForBeginners.md)
- [How to run Pharo from the command line](General/HowToRunPharoFromCommandLine.md) - How to run pharo from the command line.
- [Glossary](General/Glossary.md) ![Unfinished](https://img.shields.io/badge/Progress-Unfinished-yellow.svg?style=flat)

## General

### Infrastructure

- [How to deal with baselines](General/Baselines.md) - Configure your project and its dependencies.
- [Setup your CI through github actions](General/GithubActions.md) - Setup your CI via GitHub actions for your Pharo projects.
- [Pharo code export formats](General/ExportFormats.md) - Explanations about code formats used to export code to VCS such as git.
- [How to deploy a pharo application](General/DeployYourPharoApplication.md) - A guide to deploy a Pharo application.
- [Windows 10 Subsystem For Linux (WSL)](General/Windows10SubsystemForLinux.md) - Getting Pharo to run on Windows 10 Subsystem for Linux.
- [Using CJK (Chinese, Japanese, and Korean) characters](General/CJKCharacter.md) - Guide to help you configure Pharo to support Chinese, Japanese, and Korean characters.
- [Using CJK input methods](General/CJKInputMethod.md) - Guide to help you configure Pharo to support CJK input method.
- [Tweaking big images](General/TweakingBigImages.md) - Tips to make large pharo images more responsive.
- [Image file format](General/ImageFileFormat.md) - Documentation about binary format of Pharo images.
- [How to setup a travis build](General/Travis.md) - How to have automated build on travis

### Pharo Language

- [Extension methods](General/Extensions.md) - How to extend existing classes in your packages.
- [Traits](General/Traits.md) - Structure to build classes via composition.
- [Some cool snippets in Pharo](General/CoolSnippets.md) - A cook book to answer common needs of a Pharo developer.
- [Progress bar](General/ProgressBar.md) - Display a progress bar to give feedback to the user.
- [Morphic Layouts](General/Layout.md) - Documentation about the layout management in the Morphic Library of pharo.
- [Pragmas](General/Pragmas.md) - A guide on Pragmas, annotations to compiled methods to add additional properties.
- [Coding conventions](General/CodingConventions.md) - A list of convention to follow when writing Pharo code.
- [Exceptions](General/Exceptions.md) - How Pharo's exceptions work and explanations on how to use them.
- [Sorting collections](General/SortingCollections.md) - How to sort collections with Pharo's built-in API.
- [Sessions management](General/SessionsManagement.md) - Documentation on setting up start-up and shut-down actions in Pharo.

### Pharo Tooling

- [Playground](General/Playground.md) - Documentation on the usage of Pharo's playground.
- [Profiling](General/Profiling.md) - Measure the time and space your program takes to execute.
- [Menubar and World menu](General/MenuBar.md) - A guide to configure and customize Pharo's menubar and world menu.
- [Iceberg on Windows workaround](General/IcebergOnWindows.md) - Troubleshooting for some issues appearing when using Iceberg on Windows.
- [Inspector](General/Inspector.md) - Documentation on the usage of Pharo's inspector.
- [Refactoring](General/Refactorings.md) - Documentation on the usage of Pharo refactoring's tool.
- [Settings](General/Settings.md) - How to use Pharo's settings system to define your own settings.

## Pharo projects

<!-- - [How to deal with files](PharoProjects/Files.md) ![TODO](https://img.shields.io/badge/Progress-TODO-red.svg?style=flat) -->
<!-- - [Objects serialization](PharoProjects/ObjectsSerialization.md) - Lists possibilities to serialize your objects on disk. ![TODO](https://img.shields.io/badge/Progress-TODO-red.svg?style=flat) -->
- [Announcer](PharoProjects/Announcer.md) - Implementation of the observer design pattern built-in Pharo.
- [Basic interactions with OS](PharoProjects/OS.md)
- [Cursor](PharoProjects/Cursor.md)
- [Dynamic variables](PharoProjects/DynamicVariables.md)
- [Numbers](PharoProjects/Numbers.md)
- [Rich text](PharoProjects/RichText.md)
- [WebBrowser](PharoProjects/WebBrowser.md) - A project to open a link in the default web browser.<!-- - [Metalinks](PharoProjects/Metalinks.md) ![TODO](https://img.shields.io/badge/Progress-TODO-red.svg?style=flat) -->

## Pharo and OpenSmalltalk Virtual Machine
- [Pharo VM documentation map](PharoVirtualMachine/pharo-vm-map.md) -

## External projects
### Data exchange
- [CSV support](ExternalProjects/Export/CSV.md)
- [JSON support](ExternalProjects/Export/JSON.md)
<!--
- [XML support](ExternalProjects/Export/XML.md) ![TODO](https://img.shields.io/badge/Progress-TODO-red.svg?style=flat)
- [HTML support](ExternalProjects/Export/HTML.md) ![TODO](https://img.shields.io/badge/Progress-TODO-red.svg?style=flat)
- [Arff support](ExternalProjects/Export/Arff.md) - Arff is a format defined by [Weka](http://www.cs.waikato.ac.nz/ml/weka/) to be used for data importation. ![TODO](https://img.shields.io/badge/Progress-TODO-red.svg?style=flat)
-->

<!--
### Data structures
- [DataFrame](ExternalProjects/DataStructures/DataFrame.md) ![TODO](https://img.shields.io/badge/Progress-TODO-red.svg?style=flat)
-->

## Migration guidelines

- [Migrating Streams from Pharo 6.1 to Pharo 7.0](Migration/MigrationToPharo7.md)

## External resources
- [Pharo Community](ExternalResources/Community.md) - Various links of people involved in Pharo community. Helps to discover Pharo ecosystem.
- [Contributing to Pharo](https://github.com/pharo-project/pharo/wiki/Contribute-a-fix-to-Pharo) - Official tutorial on how to contribute to Pharo using Iceberg.
- [Generating your own Pharo images (Bootstrapping)](https://github.com/carolahp/pharo/tree/candle) - Tools for generating small Pharo images from source code.
- [Magritte3 Wiki](https://github.com/seandenigris/Magritte/wiki) - Wiki related to Magritte3.
- [Sean's wiki about pharo](https://github.com/seandenigris/pharo/wiki) - The wiki of Sean P. DeNigris related to Pharo.
- [#pharotip hashtag on twitter](https://twitter.com/hashtag/pharotip) - Tweets to help new users to easily get going with Pharo, started by [@astares](https://twitter.com/TorstenAstares).

![CC](https://mirrors.creativecommons.org/presskit/icons/cc.svg)
![BY](https://mirrors.creativecommons.org/presskit/icons/by.svg)

<!---
Badges:
* ![TODO](https://img.shields.io/badge/Progress-TODO-red.svg?style=flat)
* ![Unfinished](https://img.shields.io/badge/Progress-Unfinished-yellow.svg?style=flat)
* ![Review](https://img.shields.io/badge/Progress-Review-blue.svg?style=flat)

-->