search

hpi-swa-lab / SqueakByExample-english

An introductory book about the Squeak/Smalltalk programming system, guiding students and developers through the environment, language, tools, and the Morphic framework by means of a series of examples and exercises.
https://www.lulu.com/shop/patrick-rein-and-christoph-thiede/squeak-by-example-60/paperback/product-8vr2j2.html
Other
24 stars 6 forks source link
book latex morphic smalltalk squeak

readme

Squeak by Example

📕 Make Book Latest release Latest preprint

Squeak is a modern, open-source development environment for the Smalltalk programming language promoting a vision of an environment where everything is an object and anything can at run-time.

Squeak by Example, intended for both students and developers, will guide you through the Smalltalk language and the Squeak environment by means of a series of examples and exercises. The book helps you getting started with an initial tour of the environment before introducing the details of the language, the standard library, the tools, and the Morphic framework.

How to get this book:

order print from lulu download free PDF

Overview of all editions:

Edition PDF Printed
Squeak by Example 6.0 (latest release)
(ISBN: 978-1-4476-2948-1)		 PDF - 6.0 lulu
Squeak by Example 5.3.1 PDF - 5.3.1 (not available)
Original 2007 edition
(Andrew Black, Stéphane Ducasse, et al.)		 PDF lulu
Latest prerelease (bleeding edge!) PDF (not available)

Other retailers

Please consider buying the book on lulu if possible as it results in more royalties for the Squeak community.

amazon

How to cite:

BibTeX 
@book{thiede2023squeak,
    author = {Christoph Thiede and Patrick Rein},
    title = {Squeak by Example},
    volume = {6.0},
    year = {2023},
    numpages = {328},
    url = {https://www.lulu.com/shop/patrick-rein-and-christoph-thiede/squeak-by-example-60/paperback/product-8vr2j2.html},
    pdf = {https://github.com/hpi-swa-lab/SqueakByExample-english/releases/download/6.0/SBE-6.0.pdf},
    publisher = {Lulu},
    isbn = {9781447629481}
}

Repository structure

The main file is SBE.tex. Chapters are in subdirectories. You can latex either the entire book, or each individual chapter. Each chapter file starts and ends with the same incantation which will optionally include macros or end the document if it is latexed individually.

Use the \ct{} macro for in-line code. Use the {method} {classdef} {example} and {script} environments for multi-line code.

If you add a new chapter:

IMPORTANT: Please check out a fresh copy of the book and compile the book to verify that you have added all the dependent files (e.g., figures).

Build process

The PDF of the book is built via GitHub Actions on each commit, which includes the execution of internal tests, the check of TEX-inlined @TEST assertions, and the generation of screenshots that are described by figure scripts. Two PDFs are created, one for the latest Squeak release and one for the current Trunk version.

You can download the latest version of the book from the Releases page.

The usual workflow to add a scripted screenshot to the book is as follows:

  1. Open the relevant .tex file and insert the following snipped before the \figure definition:

    \begin{ExecuteSmalltalkScript}
SBEScreenshotRecorder writeTo: './figures/<name>.png' building: [:helper |
self shouldBeImplemented
]
\end{ExecuteSmalltalkScript}

\begin{figure}
  \centering
  \includegraphics[scale=0.65]{<name>}
  \caption{<caption>.\label{fig:<name>}}
\end{figure}

  2. Insert figure name, caption, and script generation logic in the template above. Browse the repository to find existing examples.

    Tip: You can also use SBEDebuggingScreenshotRecorder instead of SBEFigureBuilder for testing your screenshot script right in the image (the file won't be saved on disk in this case).

  3. Test your script by doing SBEFigureBuilder buildAllTexFigures (maybe you need to set #resourceDirectory before) or SBEFigureBuilder buildFiguresWith: FSPath * 'your' / 'path'.

  4. Build the PDF using the Makefile to make sure your screenshot looks well.

  5. Commit! 🚀 The PDF will automatically be built on the CI now ...

  6. If the build process has completed, you can watch the results in the Actions tab of the GitHub repository by opening the latest successful build and scrolling down to the artifacts.

To build the PDF manually, do the following:

I. Installation

  1. Get a support Squeak image (either the latest release or the latest Trunk image)

  2. Open the Git Browser and clone this repository. Install missing dependencies as specified in the baseline if necessary.

    Alternatively, you can load the project via Metacello, but you won't be able to commit changes back to the repository without cloning it first:

    Metacello new
baseline: 'SBE';
repository: 'github://hpi-swa-lab/SqueakByExample-english:master/SmalltalkSources';
get;
load.

  3. Make sure to set the resource directory to the path of your working copy:

    SBEFigureBuilder resourceDirectory: FileDirectory default asFSReference / 'path' / 'to' / 'workingCopy'.

  4. Install any Linux distribution.

II. Building

  1. Do it:

    SBEFigureBuilder buildAllTexFigures.

  2. From the shell, run "make" in the working copy.

For more insights into the build process, have a look at the Makefile and the .github/worfklows/build.yml.

Printing

The book has been reformatted to 6"x9" (for Lulu). If you want to print any part of the book, you will find that printing 2 up at 140% works well.

Release Process

1. Actual release

2. Prepare the repository for the next edition

Style Rules

Testing

Tests are automatically generated from the LaTeX sources.

Grab a recent Squeak image and move it to the folder Squeak book folder. Do not use a 1-click image, since the actual image should be located at the same level as the SBE.tex file.

To run the tests, load the package SBE-Testing from this repository. Then evaluate the following expression in a workspace:

SBEmain new runTests

This will automatically extract and run the tests in the LaTeX sources of the Squeak by Example book. It will also load the hands-on exercises, and check that they are working. (Some tests may also be included from the dependent hands-on packages.)

This will parse (using Regex) the SBE.tex to locate the included chapter files, parse each chapter file to search for @TEST annotations, generate test case classes for each chapter with tests in a new category SBE-GeneratedTests, and generate a test method (numbered by the line number in the chapter) for each test found. (NB: Any old generated tests are removed before new ones are generated.) Finally, by sending "runTests", a TestRunner is opened on the new category, and all those tests are run.

How to write tests in LaTeX

A sample test in the BasicClasses looks like this:

\begin{code}{@TEST}
a1 := { { 'harry' } } .
a2 := a1 shallowCopy.
(a1 at: 1) at: 1 put: 'sally'.
(a2 at: 1) at: 1 --> 'sally'
\end{code}

The "print it" invocation (-->) will generate an assertion.

The generated source code looks like this:

test204
    a1 := { { 'harry' } } .
    a2 := a1 shallowCopy.
    (a1 at: 1) at: 1 put: 'sally'.
    self assert: [ (a2 at: 1) at: 1  ] value printString = '''sally'''

You may also silently declare or initialize variables immediately after @TEST, and you may now place comments after the test string:

\begin{code}{@TEST |a b|}
a := b := 'hello'.
a == b --> true "two variables but one object"
\end{code}

The generated TestCase subclass is SBEBasicClassesTestCase.

The generated tests can be removed by evaluating SBEmain removeOldTestCategory. This is done automatically whenever you do SBEmain new runTests.

LaTeX version

Please use at least texlive 2017. http://www.tug.org/texlive/

Figures and OmniGraffle files

Please be sure to use Lucida Sans, not Helvetica, or you may have problems uploading the PDF to Lulu. See the font embedding FAQ on lulu.com See more detailed instructions in Cover/README.txt

Style files

To inform latex about the location of local style files, set the following environment variable (tcsh):

setenv TEXINPUTS ./local//:../local//:
    or (bash):
export TEXINPUTS=./local//:../local//:

If you are using a GUI like TeXshop, you must set the environment variable in ~/.MacOSX/environment.plist :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>TEXINPUTS</key>
    <string>./local//:../local//:</string>
</dict>
</plist>

NB: You may need to logout and login again after creating or modifying this file. Note colon at end of TEXINPUTS that means "append current value here" (eg local has higher priority). Double slash means search recursively.

Bibliography

The bibliography can be found in the Bibliography folder. When the make command is run, the bibliography is automatically built as well.

Smalltalk Sources

The "Squeak by Example" Monticello Repository can be found as a FileTree repository in the SmalltalkSources folder but is best loaded and saved using Squot.

The package SBE-Testing includes as dependencies the code for the hands-on chapters. It will run all the test code in the latex sources and exercise the hands-on code.

All packages that contain examples relevant to the user are also hosted at SqueakSource at http://www.squeaksource.com/SqueakByExample60/. Before releasing a new edition of the book, make sure to update these sources using the SBESqueaksource class from the SBE-Extract package. The SqueakSource repository is world-readable and can be written by the administrators, which are currently ct and pre.

Coding Style Guide

License

This work is licensed under Creative Commons Attribution-ShareAlike 3.0 Unported http://creativecommons.org/licenses/by-sa/3.0/

You are free:

Under the following conditions:

Attribution. You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work). Share Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license. For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to this web page. Any of the above conditions can be waived if you get permission from the copyright holder. Nothing in this license impairs or restricts the author's moral rights.

Disclaimer

Your fair dealing and other rights are in no way affected by the above. This is a human-readable summary of the Legal Code (the full license).