{"id":22742010,"url":"https://github.com/instantiations/tonel-vast","last_synced_at":"2025-04-14T07:52:18.492Z","repository":{"id":52407239,"uuid":"205748565","full_name":"instantiations/tonel-vast","owner":"instantiations","description":"Tonel file format writer and reader implementation for VA Smalltalk","archived":false,"fork":false,"pushed_at":"2025-01-08T17:57:12.000Z","size":6494,"stargazers_count":10,"open_issues_count":31,"forks_count":4,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-27T21:38:42.312Z","etag":null,"topics":["cvs","git","github","smalltalk","tonel","vasmalltalk","vastplatform"],"latest_commit_sha":null,"homepage":"","language":"Smalltalk","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/instantiations.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-02T00:26:14.000Z","updated_at":"2025-01-08T17:57:16.000Z","dependencies_parsed_at":"2024-06-24T19:31:53.863Z","dependency_job_id":"b1bf1aef-edd7-4169-8d1e-a7320ec7d61e","html_url":"https://github.com/instantiations/tonel-vast","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instantiations%2Ftonel-vast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instantiations%2Ftonel-vast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instantiations%2Ftonel-vast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instantiations%2Ftonel-vast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/instantiations","download_url":"https://codeload.github.com/instantiations/tonel-vast/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248844079,"owners_count":21170486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cvs","git","github","smalltalk","tonel","vasmalltalk","vastplatform"],"created_at":"2024-12-11T00:33:43.613Z","updated_at":"2025-04-14T07:52:18.463Z","avatar_url":"https://github.com/instantiations.png","language":"Smalltalk","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\r\n \u003ch1 align=\"center\"\u003eTonel Tools for VAST Platform (VA Smalltalk)\u003c/h1\u003e\r\n  \u003cp align=\"center\"\u003e\r\n    Providing git-friendly file format support to VAST\r\n    \u003c!---\r\n    \u003cbr\u003e\r\n    \u003ca href=\"docs/\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\r\n    \u003cbr\u003e\r\n    --\u003e\r\n    \u003cbr\u003e\r\n    \u003ca href=\"https://github.com/instantiations/tonel-vast/issues/new?labels=Type%3A+Defect\"\u003eReport a defect\u003c/a\u003e\r\n    |\r\n    \u003ca href=\"https://github.com/instantiations/tonel-vast/issues/new?labels=Type%3A+Feature\"\u003eRequest feature\u003c/a\u003e\r\n  \u003c/p\u003e\r\n\u003c/p\u003e\r\n\r\n\r\n\r\n## Introduction\r\n\r\n[Tonel](https://github.com/pharo-vcs/tonel) is a text-based file format used to store Smalltalk source code on disk, and was designed from scratch to be version control system (VCS) friendly. It is widely accepted by the Smalltalk community at this point, so Instantiations saw an opportunity to enhance ENVY (the standard VCS in VAST) by adding Tonel support for greater functionality and flexibility.\r\n\r\nDevelopment on Tonel Tools for VAST began in September 2019, and official support started when it shipped as a feature within VAST Platform 2021 (10.0.0) in March 2021.\r\n\r\nOpen source projects using Tonel for VAST can be found in the [VAST Community Hub](https://github.com/vast-community-hub) or in [Instantiations' GitHub respositories](https://github.com/instantiations).\r\n\r\n\r\n## License\r\n- The code is licensed under [MIT](LICENSE).\r\n- The documentation is licensed under [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/).\r\n\r\n\r\n## Installation\r\n\r\nWe continue to improve the Tonel support by fixing bugs and adding new features to it, if you want to use the latest version you can do it by downloading the latest version in this repository into the latest version of VAST.\r\n\r\n\r\n### Installing in VAST 2022 / 2023 / 2024\r\n\r\nTonel comes as a Feature inside the product. That means it can be easily installed from the `Transcript` -\u003e `Load/Unload Features...`. You will find two features you can install: `ST: Tonel Support` and `ST:Tonel Support, Testing`.\r\n\r\n### Installing in VAST 2021\r\n\r\n#### Loading the feature\r\nSince there were significant changes in the codebase, the update must be split in sub steps, and do intermediate updates.\r\n\r\n- Load Tonel VAST Features using `Transcript` -\u003e `Load/Unload Features...`. There you will find two features you can install: `ST: Tonel Support` and `ST:Tonel Support, Testing`.\r\n- Clone this repository locally using your preferred git tool.\r\n\r\n#### Update to intermediate version\r\n- Checkout the commit tagged as `v1.4.2`\r\n- Open Configurations Maps Browser\r\n- Right click in the `All names` list, select `Import` -\u003e `Load Configuration Maps from Tonel repository...`\r\n- Select the `.project` file of the directory you cloned in the step above\r\n- Select `ENVY/Image Tonel` and/or `Test ENVY/Image Tonel`\r\n\r\nYou might get an error during the update, since Tonel is modifying itself as it gets loaded.\r\nIf that happens, retry the import.\r\n\r\n### Update to latest version\r\n- Checkout the latest commit (master branch)\r\n- Open Application Manager\r\n- Right click in the Applications list, select `Import/Export` -\u003e `Load Applications from Tonel packages...`\r\n- Select the `.project` file of the directory you cloned in the step above\r\n- Select `TonelSystemExtensions` and import it\r\n- Open Configurations Maps Browser\r\n- Right click in the `All names` list, select `Import` -\u003e `Load Configuration Maps from Tonel repository...`\r\n- Select the `.project` file of the directory you cloned in the step above\r\n- Select `ENVY/Image Tonel` and/or `Test ENVY/Image Tonel`\r\n\r\n\r\n### Installing in VAST 9.2.x\r\n\r\n- Clone this repository locally\r\n- [Download VAST](https://www.instantiations.com/products/vasmalltalk/download.html) from Instantiations website.\r\n  - If you're using 9.2.1 checkout the [v1.1.0 tag](https://github.com/instantiations/tonel-vast/releases/tag/v1.1.0)\r\n  - If you're using 9.2.2 checkout the [v1.2.0 tag](https://github.com/instantiations/tonel-vast/releases/tag/v1.2.0)\r\n- From the Configuration Map Browser, do an `Import` -\u003e `All Most Recent Versions...` -\u003e and select the `envy/Tonel.dat` located in the root folder of your local repository clone.\r\n- Select the map `Tonel` (and optionally `Test Tonel` if you want to run its SUnit tests) and do a `Load With Required Maps` the latest version of it.\r\n- Optionally run the SUnit tests included in the map `Test Tonel` to ensure correct installation. One easy way is to right-click on the `Test Tonel` map name in the Name pane (as opposed to version pane ) and then select `Test Loaded Applications`.\r\n- Explore the [documentation](docs/).\r\n\r\n## Quick Start\r\n\r\n### Using GUI menus\r\n\r\n#### Applications\r\n\r\nYou can load individual Tonel packages as Applications or export VAST Applications as Tonel packages via Application Manager's `Import/Export`.\r\n\r\n![Application Manager](docs/img/application-manager.png)\r\n\r\nWhen loading apps using this GUI the _loader_ will attempt to detect whether the files are in a Git repository, and if a git repository is detected it will configure itself to use [git versioning](docs/strategies.md), otherwise it will use the default settings (or leave all editions open without version).\r\n\r\n#### Configuration Maps\r\n\r\nYou can also export and load Configuration Maps together with their applications from the Configuration Maps Browser.\r\n\r\n##### Exporting\r\n\r\nSelect the Configuration Maps you want to export in the names list, and then open the contextual menu and choose `Export`, and then `Export Configuration Maps to Tonel`.\r\n\r\n![Configuration Maps Export](docs/img/configmaps-export.png)\r\n\r\nThis will ask you which version of the config maps you want to export (only one version per map is allowed), where do you want to store it, as well as a few other settings.\r\n\r\n##### Loading\r\n\r\nTo load a Configuration Map in a Tonel repository into VAST, you have to choose the `Import` option in the names list, and then `Load Configuration Maps from Tonel...`.\r\n\r\n![Configuration Maps Load](docs/img/configmaps-load.png)\r\n\r\nOnce you select the available Configuration Maps, they will be loaded together with their required maps. If a required map is within the Tonel repository, then this map version will take precedence over the version specified.\r\n\r\n\r\n### Programmatically\r\n\r\nAs with the GUI options, you can also export independent Applications or whole Configuration Maps to Tonel.\r\n\r\n#### Applications\r\n\r\n```smalltalk\r\n\"Exporting to Tonel\"\r\nTonelWriter new\r\n  clearSourcesDirectory; \"deletes everything in the target directory\"\r\n  writeProjectIncluding: (Array with: MyAppCore)\r\n  into: (CfsPath named: 'my-tonel-demos').\r\n ```\r\n\r\n```smalltalk\r\n\"Loading from Tonel\"\r\n(TonelLoader readFromPath: (CfsPath named: 'my-tonel-demos'))\r\n  loadApplicationNamed: 'MyAppCore'.\r\n\r\n\"or you can load by Tonel package name\"\r\n(TonelLoader readFromPath: (CfsPath named: 'my-tonel-demos'))\r\n  loadApplicationsForPackagesNamed: #('MyApp-Core' 'MyApp-Tests').\r\n```\r\n\r\n#### Configuration Maps\r\n\r\n```smalltalk\r\n\"Exporting to Tonel\"\r\nTonelWriter new\r\n  addLatestConfigurationMapNamed: 'My Tonel Demo';\r\n  addLatestConfigurationMapNamed: 'My Tonel Demo Tests';\r\n  addApplicationsFromConfigurationMaps;\r\n  writeProjectInto: (CfsPath named: 'my-tonel-demos').\r\n```\r\n```smalltalk\r\n\"Loading from Tonel\"\r\n(TonelLoader readFromPath: (CfsPath named: 'my-tonel-demos')) loadAllMapsWithRequiredMaps.\r\n```\r\n\r\n#### More options\r\n\r\nYou can specify other options like versioning, prerequisite resolution, and others using the different strategies for each case, read the [strategies documentation](docs/strategies.md) to learn more about them.\r\n\r\n\r\n## VAST Specific features\r\n\r\nSince Tonel wasn't designed with VAST use in mind, some features are not supported by the spec and we needed to extend it to support them.\r\n\r\nYou can read [document of VAST specific features](docs/vastspecific.md) to know more about them.\r\n\r\n## Compatibility Recommendations\r\n\r\nIf you want to make your code fully compatible and interoperable with other Smalltalk dialects there is a specific document with the [recommendations for compatibility](docs/compatibility.md).\r\n\r\n## Shared Pools\r\n\r\nVAST's way of declaring and/or initializing Shared Pools is different from other Smalltalk dialects, and to explain how this work with Tonel, there is a specific document explaining [how VAST Tonel handles shared pools](docs/sharedpools.md).\r\n\r\n\r\n## Versioning and prerequisites\r\n\r\nRead the [versioning, prerequisites and base editions strategies documentation](docs/strategies.md) to learn how to configure the loader to work interactively, unattended, read the version from a git repository, etc.\r\n\r\n## Configuration Maps\r\n\r\nAlthough dependency management is outside of the scope of Tonel, VAST Platform's Tonel tools provide a way to write them to disk and later read and load them.\r\n\r\nRead the [Configuration Maps documentation](docs/configmaps.md) to learn how to use it.\r\n\r\n## Architecture\r\n\r\nThere are four main building blocks that work in layers to support Tonel in VAST Platform:\r\n\r\n### Tonel Parser\r\nParses the Tonel specific files following the same rules as the [canonical version](https://github.com/pharo-vcs/tonel).\r\n\r\n### Tonel Reader\r\nRelies on the parser to create first-class objects representing each abstraction from Tonel. E.g. _Package_, _Class_, _Method Definition_, _Method Extension_\r\n\r\n### Tonel Loader\r\nUses the reader to compile classes, methods, extensions, etc. and then create the required editions and versions in the ENVY Library.\r\n\r\n### Tonel Writer\r\nWrites to disk, in a Tonel compatible format (plus the VAST specific features described below) the Applications, SubApplications, Classes, Shared Pools, Methods, Extensions, etc.\r\n\r\nIf the Application has a class side `#tonelPackageName` selector it  will then honor it when creating the package name.\r\n\r\n\r\n## Testing\r\n\r\nThe Reader, Parser and Writer tests can be run out of the box once loaded, but the Loader tests need a little setup in order to run.\r\n\r\nOnce you clone this repository you have to configure `TonelLoaderTest` to point to the `tests` directory within the repository, since it contains the repositories used for testing the loader.\r\n\r\n```smalltalk\r\nTonelLoaderTest testRepositoriesPath: (CfsPath named: 'repo-path\\tests')\r\n```\r\n\r\n### Note about side-effects\r\n\r\nThe Loader tests will attempt to leave the ENVY Library (aka \"the library\") in the same logical state as it was before running them by means of reloading the applications that were loaded before starting and purging newly created editions, but since this can the access to the library isn't atomic (as in a single enclosing transaction) there could be leftovers if something goes wrong. So it isn't adviced to run the tests against your production library.\r\n\r\n\r\n## Versioning of this very project\r\n\r\nThe versioning of this particular project is somewhat special because there are several versions going on in parallel: the version that comes with the VAST release, the config map version of each commit and and release version of Github releases. Because of that, the versioning strategy has been changing since the beginning of the project, looking for the optimal one. \r\n\r\nStarting with VAST 10.0.0 we decided to adopt a versioning strategy that might eliminate the multiple version naming, and help in mapping the different versions together.\r\n\r\nGuidelines:\r\n* The `Tonel Support` feature (and/or its Test variant)  must be loaded before loading this project into a VAST image\r\n* The `ENVY/Image Tonel` version that comes as a feature in a VAST release (currently v 10.0.2) is considered the \"trunk\"\r\n* The code from this repository is loaded on top of the configurations maps loaded in the previous points\r\n* When versioning configuration maps both the \"trunk\" version identifier and a sequential version will be used as the version name, e.g. `v 10.0.0  [v1.3.6]`.\r\n* Once a new Github release is published, the `v1.3.6` part above will likely be re-published as `v1.4.0` (the version of the release).\r\n* When there is a VAST release that integrates one of the Github releases as a built-in _feature_, it will rename `v 10.0.1  [v1.4.0]` to something like `v 10.0.2  [543]` (being the `543` the VAST build number), but both versions will likely share the same internal timestamp.\r\n\r\n## Additional Resources\r\n\r\n* The webinar [\"Getting Started with Tonel Tools In VAST\"](https://www.youtube.com/watch?v=qnunJ1y3x70), which discussed how to use the new Tonel Tools features with step-by-step instructions and practical examples. \r\n\r\n## Roadmap / Next steps\r\n\r\nSee the [roadmap document](docs/roadmap.md) for further details.\r\n\r\n\r\n## Acknowledgments\r\n\r\n- [Mercap Software](https://github.com/Mercap) for their first draft on the Tonel writer\r\n- Github repository layout was generated with [Ba-St Github-setup project](https://github.com/ba-st/GitHub-setup).\r\n\r\n## Contributing\r\n\r\nCheck the [Contribution Guidelines](docs/CONTRIBUTING.md)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstantiations%2Ftonel-vast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finstantiations%2Ftonel-vast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstantiations%2Ftonel-vast/lists"}