Starting with Etoys Development

Skip to end of metadata
Go to start of metadata

Audience of this Page

Software developers, students and users who wish to make fixes, changes or enhancements to the Squeak code underlying Etoys.

Goal of this Page

The goal of this page is to encourage contributions to Etoys, describe the Etoys development community process, and help develop Etoys further.

What to read on this page?

  • Squeak or Smalltalk developers probably only need to read last four paragraphs, starting with Who Maintains Etoys(probably skipping the last chapter anyway).
  • A beginner or intermediate Squeak developers may want to keep reading,

Not a Goal of this Page: Creating Etoys Projects


A sample Etoys project is on the right.

It is not a goal of this page top teach how to create Etoys projects using the Etoys tiles. If you are new to Etoys, or want to create an Etoys project using tiles, see Installing and Using Etoys.

 

Etoys History and how do Etoys Relate to Squeak and Smalltalk

Squeak is a free version of Smalltalk. Squeak is also the environment in which Etoys are developed. The relationship between Squeak and Etoys is somewhat difficult to describe to a new user. As an introduction: If you are a Etoys user, and want to create Etoys projects, use the links in the heading above to download, install, learn about, and use Etoys. If you indend to use the underlying Squeak development environment of Etoys, keep reading.

Etoys and Squeak use the same Virtual Machine, commonly referred to as "the Squeak VM".  However, the image where Etoys are developed is different from the image where Squeak is developed. See Paragraph Where do I download my Etoys Development Environment for the Squeak VM and Etoys image download links.

Etoys Development: Prerequisits

Developing Etoys requires background in Squeak Smalltalk development. In fact, developing and modifying Etoys requires the same skill set as developing in Squeak Smalltalk. The links below may help the process of learning Squeak. In the rest of this page, references to Squeak could read "the Squeak code and development process required for Etoys development".

Etoys Development: Existing links for Squeak / Etoys Developers

As mentioned in the paragraph above, skills required for Etoys development are mostly same as skills required to develop in Squeak. Consequently, many Squeak or Smalltalk links will help with Etoys development. This is a collection of links that may be of interest to Etoys developers:

  • Squeak by Example is an excellent Squeak online book with tutorial. You can download the book for free or buy a printed copy.
  • OLPC XO site has a wealth of Etoys development information. Most of the OLPC etoys pages are not OLPC specific, and usable for any Etoys development.
    • Smalltalk development on the XO is a detail guide describing how to develop in Squeak Smalltalk on the OLPC XO. In fact, the bottom part of this page is based on the OLPC XO page.

Etoys Development: Who Maintains Etoys? What is the License? Where do I download my Etoys Development Environment?

Etoys development, marketing, and maintenance was transferred from Viewpoints Research to the Squeakland Foundation, which was formed for this purpose. All Viewpoints Research members involved in Etoys development are active in the Squeakland Foundation. See this press release about establishing the Squeakland Foundation for more details.

Current version of Etoys is 4. Etoys 4 under a free licence - MIT licence with portions under the Apache License

By submitting any changes to the Source Repository or Etoys Bug Tracker, you are releasing your contributions under the MIT licence.

To setup an Etoys development environment:

  1. Download a recent version of the Etoys development image from http://etoys.squeak.org/download/
  2. Press the button in the top left marked "update code from server"
  3. When you are asked "Load the latest packages from the default repository" select "Yes"

This will synchronise it with the latest changes.

Etoys Development: Forums, Mailing Lists and Issue Tracking

The Etoys community solicits help with testing, and new ideas. If you find a Etoys problem or if you have an idea for improvement, here are a few pointers and links to start:

  • Discuss the problem or change on the Etoys Development Mailing list on Squeakland.
  • Etoys bugs and enhancement suggestions are maintained at Squeakland Etoys issue tracker. Use the Quick Search field on the top right to find issues. You may want to check if similar issue has been reported. For example, if you have a problem with the Painter tool, type "paint" or "painter" into the search field on the top right, and hit enter.
  • If your issue is new, click on Create a New Issue on the Tracker, and describe the problem or idea details. Adding an item on this site will generate an email to the Squeakland Etoys mailing list in the first bullet.

Etoys Development: Process for Contributing an Etoys Change (fix or enhancement), and Submitting the Change for Inclusion in Release

TODO: Explain how to communicate a Monticello submission to the Inbox.

 Typical steps to contribute an Etoys change:

  • Reporter (User or Developer) discovers an Etoys problem or has an idea for a change.
  • Reporter should review existing issues in Etoys Issues Tracker to confirm the issue is new. Quick Search is available on the top-right on every page on the Issues tracker site.
  • Reporter reports a bug or enhancement on Etoys Issues Tracker. Note: You must have an account there and be logged in to report a bug.  Create an account on Etoys Issue Tracker. 
  • If you are a Developer, and choose to fix an issue, edit the issue on Etoys Issues Tracker, and choose your name as "Assign To".
    • Issue status is set to "Open" by default.
  • Developer clicks "Assign this issue to me" in the left pane. 
    • Issue "Assignee" is set to developer.
  • Developer clicks "Start Progress" in the left pane, to let others know the issue is being worked on.
    • Issue status changes to "In Progress".
  • Developer works on the issue. To see an example of a code change, please see paragraph below, Making an Etoys Change for details.
  • When Developer is finished with coding and testing and wishes to submit the change, he/she should export the code change (the code "difference", called a Changeset) and clicks "Attach file" on the left to attach the Changeset file to the bug. See below what is a Changeset, and also the paragraph below, Making an Etoys Change for details.
  • When Developer is finished, he/she clicks "Resolve issue", and set resolution to "Complete". Changing status to "Resolved" will trigger an email to Reviewers (the software team).
    • Issue status changes to "Resolved".
  • A Reviewer will test,  and depending on the situation, approve / modify / reject the change.
  • The Reviewer clicks "Close issue" when she/he approved the code change. Reviewer submits the Changeset into Monticello at http://source.squeak.org/etoys.html (TODO check this)
    • Issue status changes to "Closed".
  • Other Etoys developers click on "Help->Update Code from Server" the update stream is loaded into his/her Etoys application. Once a developer has done that, their Etoys runs with the change.

Etoys Development: Making an Etoys Code Change - a Developer Tutorial with Screenshots

 TODO: this tutorial needs to be updated to reflect the Monticello-based development process than began in April 2010 to make the next release after Etoys 4.0

This is a short tutorial describing the steps a developer needs to perform to perform a bug fix and submit the work for inclusion in Etoys release. It has been based on a more detailed tutorial by Yoshiki Ohshima for the OLPC XO.

In this section, we will go through one Etoys development cycle using a simple example. We will make up a very simple "mock bug" in Etoys, and go through the steps of opening a bug on the Etoys Issue Tracker, use Squeak development tools to find the code that "causes" the bug, fixing the bug, saving the code change in a Changeset File, and "attaching it" to the reported bug. Please note our "fix" is not a desired result - merely an exercise!

  • Make up a very simple "mock bug" in Etoys: Let us assume we do not like the Painter Canvas position after it is dragged out, and want to change the position. To experience what is hapening, start Etoys, and from the black task bar on top:
    • Click the Painter image in the black task bar on top (Painter image looks like painter's palette)
    • The misty Painter Canvas lands roughly in the middle. Let us assume we consider this a bug, as we want the canvas to land on the left top.

       

 

 

 

  • Next we learn how to utilize the Squeak development tools to find the code that "causes" the bug.
    • Etoys are great at finding the action code that runs when clicking on the Painter.
    • To find the action code, we first need to find the Painter button.
    • Halo-Click (Right Click on 3-butoon mouse) four times on the Painter Button until the SugarButton halo appears. This indicates the button Morph was found.
    • To understand what a halo is, refer to Squeak Morphic tutorials. For now, it is sufficient to say that every visible object is called Morph. Every morph has a halo that can be displayed by halo-clicking (right mouse click on 3 button mouse) on the Morph. The halo consists of about 10 images displayed around the morph's boundaries. Each image has a specific action that can be done on the morph.
       
       
       

 

  • Next we find the action code associated with the Painter SugarButton click.
    • In the above image, click on the white menu symbol in the halo (right of the x in top left corner). The SugarButton menu will appear - it is shown on the right. Click on the SugarButton pin on top right - this will make the menu "pinned" - it will stay displayed. In the SugarButton menu, click on the Debug->Explore menu item. Object Explorer on the Painter SugarButton appears.
    • Note the "target" and "actionSelector" menu items - they define the code that will run when the painter Button is Select-clicked (Left Clicked).
    • Value of "target" is "a SugarNavigatorBar", value of "actionSelector" is "#doNewPainting". "a SugarNavidatorBar" is the object on which the method named "#doNewPainting" is performed. This is the code performed on the Painter SugarButton click - the code we are looking for.

       
       

 

 

  • To find code that runs when the painter is clicked, click on the background.
    • The World Menu appears.
    • In the World manu, click on Open, then Browser. 
    • The System Browser Appears. It can be used to browse (investigate) the system classes.

       
       

 

 

 

  • Now we will find definition of the SugarNavigatorBar class, and what it does when #doNewPainting method is executed.
    • Position your mouse on the top-left pane of the system browser. It must stay there for the next action. Our next action is hitting Alt-f. Alt-f will ask for the name of the class we are looking for. After Alt-f a dialog appears, asking for class name we are looking for. Type SugarNavigatorBar, then click on Accept.

       
       

 

 

 

  • Click on SugarNavigatorBar on the left, then click on doNewPainting in the right System browser pane. Code running when  Painter is clicked in the bar appears on the bottom pane of SystemBrowser.

     
     

 

 

 

  • Change the code to set the new position, they type Alt-s (Accept, which is save in Etoys). A menu will appear prompting you for your initials. 

 

 

 

 

  • So far we made a code change, and saved it. Now try what happens when you click on the Painter. It now opens in the new position we defined.

     

 
 

 

 

  • But how do we export the code change we made and share it with everyone, or attach it to the bug? This process is called "finding the changeset" and "filing out the Changeset" Filing out a changeset basically exports the changes to a file, which can attached to a bug report on Etoys Issue Tracker (or emailed to the list for installation), and then "loaded" or "imported" into another developer's image. 
  • Steps to find the changeset (all changes we made so far):
    • Click on the background. World menu will show.
    • Pin it and click on "open". "Open menu" shows.
    • Pin the open menu. In the "open menu", select-click (left click) on "simple change sorter". Simple change sorter is the tool which allows to manipulate Changesets. This is what you will see:


 

 
 

 

 

  • Steps to "File out" a changeset.
    • Because we did not give our changeset a name, it is called Unnamed now.
    • Let us name our changeset.  Popup-click (midle click on 3 button mouse) on the Unnamed in the left pane. The Changeset tool popup appears. 
    • Click on "rename change set (r)", and give it a descriptive name (but not too long).  The convention used here is to put a hyphen and your initials at the end of name. (e.g., "BlahBlah-mz").
    • Another convention used here is to add "preamble".  From the pop-up menu, choose "add preamble (p)".  If you are asked your name, give it your full name and hit OK.  The template of the preamble, which basically is a structured comment, is inserted.  There, you see some text that reads "<your descriptive text goes here>".  Replace it with descriptive text.  Make the first sentence a one-line summary: and then put more explanation below.
    • If the changeset requires a pre-install and/or post-install action, you can add them.  For a pre-install action, type executable Squeak statements right after the ending double-quote.  When you try to accept it, you will see a warning dialog but it is ok.  For a post-install action, choose "add postscript..." and edit the text pane that shows up.  For examples, browse many changesets in  http://tinlizzie.org/updates/etoys/updates/ and http://squeakland.org/updates/ and you'll get the idea.
    • Click on "file out" (save) to save the changes in a file.

 
 

 

 

  • The "filed out" Changeset is now saved in a file named "ModifiedInitialPaintCanvasPosition-mz.1.cs". "cs" stands for "change set". You can verify it by clicking World->Open->File List.
     
     
  •  
    Next, Submit the bug fix for inclusion in Etoys, by attaching the Changeset file to the reported bug. TODO screenshot of bug tracker. By submitting any changes to the Etoys Bug Tracker, you are releasing your contributions under the MIT licence.
  • At this point, developers work is done. Reviewer(s) will review. and potentially modify the Changeset, and, if accepted, submit the Changeset to Monticello at http://source.squeak.org/etoys.html. (TODO check this.) When an Etoys developer clicks on "World Menu -> Help->Update Code from Server" update stream with the fix is loaded into his/her Etoys application. Once a developer has clicked "Help->Update Code from Server", he/she is running code with the fix. (TODO check this.) End users have read-only images, and don't have access to an update stream.
  • There are some people who are given the write access to the update stream, which is normally generated automatically from Monticello.  If you get write access to http://source.squeak.org/etoys.html, you can "commit" changes directly to Monticello.  From the File List, select the change set you would like to publish.  The version number part of the file name is not welcomed, so you choose "remove version #" menu item or button in the File List to remove the version number and extra period.  Then, open the pop-up menu and choose "broadcast as update".  The developer image is configured to send the change to the publicly visible update stream, update the updates.list file in the server directory that keeps the sequencing of them (the changes file automatically gets a sequence number when you upload it).  Once it is done, people can fetch them from the server. (TODO I struck these last four sentences as they look wrong - should they be deleted?)
  • It is a good idea to keep a "pristine" image.  With that image, you just load updates and save it.  When you would like to test your changeset before publishing, file it into this image and things work as expected.  (For certain things that may involves image start up or shut down, you would make a copy of the pristine image by "save as" and try the change set in that image.  The trick is to keep the pristine image really pristine.)
  • Occationally, you might have to revert a change set in the update stream.  (e.g., a change that causes an error.) In that case, select "etoys" entry in the File List (usually close to the bottom of the list) and give the password for tlvpri user. Rename the offending changes file, and edit the updates.list file to remove the line.  (Note that the line-ending of these files has to be CR (0x13).  If you do it from the Squeak's File List, it usually does the right thing.  But some people may prefer to edit them locally by Emacs (with proper buffer coding system to ensure the line ending convention) and then send the file via a regular WebDAV client.

This concludes the brief tutorial.

Labels

development development Delete
dev dev Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.