Skip to content

Migration from 0.12 to 0.13

Jump to bottom
herby edited this page Oct 15, 2014 · 19 revisions

copied from a mail Herby Vojčík, 5th Oct 2014 (needs further editing)

Quick migration for a simple project

  1. Create a new Amber 0.13 project with amber init
  2. File in the code from the previous version.
  3. In index.html
    • Rename smalltalk to amber in loader callback (shift in convention, not crucial).
    • Add .globals when accessing smalltalk globals.

Note: this only works for simple project with single package holding all the production code (and optionally another one for tests). If you create more packages, you must do additional steps involving deploy.js / devel.js and Gruntfile.js files.

Detailed description

0.12 project layout

  • index.html with:
<head>
  <script src="path_to_amber/support/requirejs/require.min.js"></script>
  <script src="path_to_amber/support/amber.js"></script>
</head>
<body>
  <script>
    require.config({paths: {
      /* project mappings */
      /* library mappings */
    }});
    require(["amber/devel|deploy" /*, packages */, function(smalltalk){
      smalltalk.initialize({/*options*/});
      smalltalk.globals.SomeClass._someStartMethod();
      // if older, previous line may lack .globalsk
     });
  </script>
  // if code outside needs to call smalltalk, it must be
  // require('amber/helpers').globals.SomeClass._aMethod();
</body>
  • src directory (or js/st directory if older) with Amber Smalltalk app code
  • libraries in bower_components (or custom layout)
  • tooling support libs in node_modules, only needed for development
  • Gruntfile.js (may be missing) with hand-written tasks for:
    • recompilation
    • running tests

0.13 default (amber init-created) project layout

  • index.html with:
<head>
  <script src="the.js"></script>
</head>
<body>
  <script>
    require(["app", function(amber){
      amber.initialize({/*options*/});
      amber.globals.SomeClass._someStartMethod();
    });
  </script>
  // if code outside needs to call smalltalk, it must be
  // require('amber/helpers').globals.SomeClass._aMethod();
</body>
  • src directory with Amber Smalltalk app code
  • devel.js and deploy.js files with sets of packages to load
  • config.js file with generated amd mappings
  • the.js file with generated loader code
    • just loader in devel mode,
    • whole app packaged in one file in deploy mode
  • local.amd.json file with project mappings
  • foolib.amd.json files with library mappings (per library folder)
  • libraries in bower_components (or custom layout)
  • tooling support libs in node_modules, only needed for development
  • Gruntfile.js with tasks for:
    • recompilation
    • running tests
    • computing amd config from *.amd.json (regenerates config.js)
    • switching between devel / deploy mode (regenerates config.js, then the.js)

Migration process

As can be derived from differences above, migration steps involve:

  • Renaming 'smalltalk' to 'amber' in loader callback (shift in convention, not crucial).

  • Adding .globals when accessing smalltalk globals.

  • Moving app-level amd mapping into local.amd.json file.

  • Specifying external libraries amd mapping (unless they already contain local.amd.json, which may be the case for amber-specific libraries; amber core as well as helios do have one) in libdir.amd.json file(s).

  • Listing production package set in deploy.js.

  • Listing development package set in devel.js.

  • Adding bookkeeping tasks into Gruntfile.js (and installing their npm dependencies with --save-dev), including:

  • Including requirejs as npm devDependency (npm install requirejs --save-dev).

  • Getting familar with different chores:

    • when new production package added, update deploy.js (not index.html) and Gruntfile.js (to include it in compilation and testing)
    • when new test package added, update devel.js (not index.html) and Gruntfile.js (to include it in compilation and testing)*
    • when new external library added, add its mapping as libdir.amd.json (not into index.html; libdir being name of directory when lib was installed), add it to deploy.js or devel.js (where it belongs), and rerun 'grunt devel' (to regenerate config.js and the.js).

  • When developing a library, not an app, there is technically no need to have two sets and deploy / devel modes, as one is always in devel mode with library. OTOH, you can have very simple app there that includes the lib, that way you can test how it behaves when deployed in an app.

  • Also, when developing library, it is crucial to select good namespace to be present in local.amd.json, as client of the library will automatically get mappings in library's local.amd.json integrated in their apps.

There is a two-space problem with listing packages to config files. Hopefully the future will bring a solution where there will only be one place to list, not three ones

  • devel.js / deploy.js
  • Gruntfile compile task
  • Gruntfile test task

More information on config.js and local.amd.json see Amber-config

Clone this wiki locally