A joint project between Chip Gracey and Stephen M Moraco. Reimplementation Pnut for Windows in a platform agnostic language.
While this is no longer our first release, we hope is that our community can help us expand our testing beyond what we've been able to do to help us find any compilation issues we may not have found. Our regression test suite is large - it compiles hundreds of .spin2 fixtures and compares the output byte for byte against Windows PNut, and it generates coverage reports that let us quickly find regions of code we haven't tested - but there is no such thing as too much testing!
The page Testing PNut-TS will help you learn how to test and identify what to report when you find an issue.
On this Page:
- PNut-TS Features
- Installing PNut-TS installation notes for the supported platforms
- Repository Configuration - more about this Repo.
Additional pages:
- PNut-TS Command-line - command line reference
- PNut-TS Preprocessor - conditional compilation support
- PNut-TS Repository notes - how to build, run tests, etc.
- PNut-TS Coverage notes - latest coverage status, how to run coverage, etc.
- PNut-TS Project Goals - our thoughts as we started this project
- PNut-TS ChangeLog - history of releases (Including what's new in this release!)
- P2_PNut_Public - Pnut (for Windows) source is currently found in the Parallax Repo
The features of this new implementation are:
- A full P2 Compiler (equivalent to PNut on Windows) for all platforms
- Written in a language which is relatively easy to maintain
- A command line tool with standard option processing
- Has a full featured light-weight preprocessor
- Listing, object, and binary compatible with PNut of same version.
(PNut v43, initially (at testing release), now at PNut v55 with this release.) - A persistent object cache that skips recompiling child objects whose inputs have not changed - including inputs further down the tree, such as an object your object uses, or a file embedded with
DAT ... FILE(as of v1.55.4) --cache-verifyproves a cached build is honest: it compiles the project a second time without the cache, in a separate process, and fails the build if the two results differ (as of v1.55.4)- A warning when one build reaches byte-identical source through two different paths, naming both files - the build still succeeds, but duplicated source is a structural smell only the compiler can see (as of v1.55.4)
- The cache is checked for correctness, not just for speed: as of v1.55.5 a cached object also carries its nested objects'
debug()information, so a cached build with-dproduces the same binary as an uncached one whichever program filled the cache first (upgrading discards any existing cache, so the first build after it recompiles) - Memory map files (
-m) naming each compiled image and each instance that runs it, with the address range, size and VAR block of every instance (the.mapformat changed again in v1.55.4 and v1.55.8 - see the CHANGELOG if you parse these files) - Internal table-size-limits are now easy to adjust if we find a need.
Install .zip files available for each release:
| Archive Name | Operating System | Architecture | Contents |
|---|---|---|---|
| pnut-ts-linux-arm64-{MMmmpp}.zip | Linux, RPi | ARM 64 bit | pnut_ts/ folder |
| pnut-ts-linux-x64-{MMmmpp}.zip | Linux | Intel x86-64 bit | pnut_ts/ folder |
| pnut-ts-macos-arm64-{MMmmpp}.zip | macOS | Apple Silicon | DMG installer |
| pnut-ts-macos-x64-{MMmmpp}.zip | macOS | Intel x86-64 bit | DMG installer |
| pnut-ts-win-arm64-{MMmmpp}.zip | Windows | ARM 64 bit | pnut_ts/ folder |
| pnut-ts-win-x64-{MMmmpp}.zip | Windows | Intel x86-64 bit | pnut_ts/ folder |
NOTE: where {MMmmpp} is the packed release version. (E.g., 014303 means v1.43.3, 015107 means v1.51.7)
Installation is pretty easy for PNut-TS. Here are the general steps: (more specific instructions links are below.)
- Identify and download the .zip file for your platform and architecture (from the latest release.)
- Unzip the file:
- Windows/Linux: Creates a
pnut_ts/folder containing the executable - macOS: Contains a signed and notarized DMG installer
- Windows/Linux: Creates a
- On Windows, Linux move the
pnut_ts/folder to your preferred install location.
On macOS open the DMG and drag thepnut_ts/folder to the /Applications folder. (This is a signed and notarized application so it should run without Gatekeeper warnings.) - Setup an environment variable (typically PATH) so that the pnut_ts (or pnut-ts) executable can be referenced from anywhere.
- Run VSCode with the Spin2 extension (v2.3.0 or later) to ensure that the installed compiler was found.
See detailed installation instructions for; macOS, Windows, and Linux/RPi.
That's really all there is to it!
This project is configured to run in a docker container. Docker is essentially a way to run stuff in a local sandboxed environment. The environment is specified by a docker image, and its main component is a snapshot of all files that are needed to run.
Wanting to clone the PNut_TS repository locally and run regression tests, or even maybe contribute to this compiler? Then start with Installing Docker Desktop to your machine. See Overview of Docker Desktop at the Docker website.
In general if you've not used docker before you'll follow these steps to get up and running:
- Install docker desktop - see install links on left panel
- Clone our repository
- Open the repo in VSCode (also shown in above "clone..." page)
VSCode will tell docker what image needs to be downloaded and then it will start the container and then ask you to [Reopen in Container]. Once you do reopen VSCode will then install the NPM packages to get your local copy ready to build and run.
Linting and formatting of TypeScript is setup using Prettier formatter and ESLint. See How to use Prettier with ESLint and TypeScript in VSCode
If you like my work and/or this has helped you in some way then feel free to help me out for a couple of ☕'s or 🍕 slices or support my work by contributing at Patreon!
Licensed under the MIT License.
Follow these links for more information: