Porting notes

From HalyardWiki

Here are notes on updating your scripts from one version of the engine to the next. For older versions of the engine, see our ancient porting notes. We have a few more possible API changes planned. You can read about them at Remaining API changes.

Contents 1 Upgrading from 0.5.12 to 0.5.28 2 Upgrading from 0.5.11 to 0.5.12 3 Upgrading from 0.5.10 to 0.5.11 3.1 Modular collects and integrated Ruby 4 Upgrading from 0.5.6 to 0.5.7 5 Upgrading from 0.5.4 to 0.5.6 6 Older engines

[edit] Upgrading from 0.5.12 to 0.5.28

There weren't a lot of API changes after this point, but here are the ones we know about:

• %browser% .path should be able to accept paths to local files, so various workarounds can go away.
• A number of private functions are no longer exported by default.
• To access the state-db, you must require it: (require (lib "state-db.ss" "halyard"))
• To access some older APIs, you must require: (require (lib "deprecated.ss" "halyard"))
• Optionally rename caution to warning (there's a glue function, so this isn't mandatory).

There's probably a couple of other minor changes that we missed--feel free to add them here.

[edit] Upgrading from 0.5.11 to 0.5.12

This release makes several API changes intended to support demand-loading. In particular, the file start.ss must now be wrapped in a module declaration, and require statements should be replaced by appropriate external-group and external-card statements.

For example, an old-style start.ss might look like this:

;; Old-style start.ss
(require (lib "util.ss" "mylib"))

(require (file "example.ss"))
(require (file "example/card.ss"))

A new-style start.ss would look like this:

;; New-style start.ss
(module start (lib "halyard.ss" "halyard")
  (require (lib "util.ss" "mylib"))

  (external-group /example)
  )

The second line in the original file would move to the end of example.ss, where it would become:

(module example (lib "halyard.ss" "halyard")
  ;; ...

  ;; At the end of new-style example.ss.
  (external-card /example/card)
  )

All non-group, non-card *.ss files should move into an appropriate subdirectory of collects. You should continue to load these files using require, as before.

[edit] Upgrading from 0.5.10 to 0.5.11

This release makes substantial changes to the directory layout of user programs. There are several API changes:

Old	New
make-native-path	resolve-content-path (for files only)
(build-path (current-directory) "Runtime" ...)	(build-path (runtime-directory) "collects" ...)
(build-path (current-directory) "Fonts" ...)	(build-path (runtime-directory) "fonts" ...)
(current-directory)	Check all uses against directory list below
abstract-path->native-path	build-path (mostly API compatible)

To update your directory structure, perform the following moves:

From	To	Notes
Media	streaming/media
LocalMedia	local/media
Graphics/script	local/branding
Graphics/cursors	local/cursors	Element-based cursors should stay where they are
Graphics	local/graphics
HTML	local/html
definitions.sqlite3	temp/definitions.sqlite3	Or just delete it
user.conf	temp/user.conf	Or just delete it
developer.prefs	config/developer.prefs
Scripts/my-lib/my-lib.ss	collects/my-lib/my-lib.ss	Non-content libraries must move to collects
Scripts/my-lib.ss	collects/my-lib/my-lib.ss	Loose top-level libraries must move into a collection
Scripts/group1/group2.ss	scripts/group1/group2.ss	Scripts defining groups or cards must be named after the group or card
Fonts	$RUNTIME/fonts
Runtime	$RUNTIME/collects	Halyard-specific collects
Runtime	$RUNTIME/plt	PLT collects
Halyard-License.txt	$RUNTIME/LICENSE.txt
Engine files	$RUNTIME

The $RUNTIME directory is now part of the Halyard distribution, not the script. Look for it in engine/win32 on Windows-based Halyard projects.

[edit] Modular collects and integrated Ruby

We now provide a script-level collects directory, which may optionally contain content files and Ruby support code:

collects/$NAME/_halyard
  local/graphics    - Graphics
  local/media       - Media files
  local/*           - Etc.
  ruby/libs         - Ruby libraries
  ruby/tasks/*.rake - Rake tasks

With this layout, referring to a graphics file named $NAME/foo.png will actually look in collects/$NAME/_halyard/local/graphics/foo.png.

Ruby code may also be stored at the top-level of a script:

ruby/libs
ruby/tasks/*.rake

You will want to grab a copy of halyard/test/config/boot.rb and copy it $HALYARD_SCRIPT/config/boot.rb. Once you've done that, you should begin every Ruby script in your project with a line like the following:

require 'config/boot'

Your Rakefile should also contain the following line:

require 'halyard/rake'

Once you do this, Ruby libraries and tasks/*.rake files will automatically be made available.

[edit] Upgrading from 0.5.6 to 0.5.7

Brian also has begun work on a new path system. So far, this requires two changes to existing code:

1. Card and group names now begin with /. For example, foo/bar is now /foo/bar.
2. You may unambiguously refer to a path using an absolute name. For example, @index still searches for the nearest node named index (using the standard acquisition rules), but @/index will always find the top-level card named /index.

This is just the start of the new path system; expect the rest of the of changes in the next release or two.

Also of interest: jump-current now actually calls jump.

[edit] Upgrading from 0.5.4 to 0.5.6

Unit test cards should now all go in the tests sequence. To get this sequence, (require (lib "tests.ss" "halyard")). You can also run the unit tests automatically from the command line with the following command:

./Halyard_d.exe -e "(command-line-test-driver)" .

[edit] Older engines

See our ancient porting notes.