Skip to content

Latest commit

 

History

History
101 lines (80 loc) · 4.08 KB

installation_and_usage.md

File metadata and controls

101 lines (80 loc) · 4.08 KB

Installation

To use TPVector, you will need to write, compile and bundle TypeScript code. If you have no experience with programming and the TypeScript development stack, this will require learning many new things. Unfortunately, I don't know any way around this.

Install the tools necessary to work with the TPVector library:

  • If you're using Windows, it's best to configure WSL (Windows Subsystem for Linux) and work in it.
  • Install esbuild, used for bundling and serving the code (install Node.js first, if needed). It is recommended to install globally with npm install -g esbuild, because TPVector is not a Node.js project, and esbuild is treated just as an external executable that needs to exist on the system.
  • Install Deno (instructions) for type-checking the code. Strictly speaking, this is optional, but extremely useful for development, and required for full IDE support.
  • Recommended: Install Visual Studio Code and the Deno extension.

Finally, clone or fork the TPVector repository on your machine.

Usage

  • Open the cloned TPVector repository in Visual Studio Code.
  • Launch the Viewer debug session (from the menu select Run | Start Debugging). This will start the Viewer task (an esbuild process that bundles and serves the code) and launch the browser with the Viewer page opened (http://localhost:4327/). The Viewer shows some demo projects, defined in demos.

(Alternatively, you can launch the esbuild server manually, or using a different IDE. You can find the esbuild command in .vscode/tasks.json, in the definition of the Viewer task.)

The TypeScript code is bundled and served by esbuild. The main logic is executed in the browser - it generates the SVGs, both for preview and for the laser software.

Where to start

Take a look at the code entry point, which is src/viewer/viewer.ts, browse the demo projects, try making changes. Changes in the code are immediately caught by esbuild, and the browser is refreshed to show the result.

Note: The esbuild process does not perform type-checking. For TypeScript correctness you need to either rely on your IDE, or run the Type-check task (configured in .vscode/tasks.json).

Creating your own projects

In a branch

Starting your own repository in a branch is the easiest way to test out TPVector.

  • In the forked TPVector repository, create a new branch for your project(s).
  • Create a my_proj.ts file in the src/demos directory (or some other directory, e.g. src/projects) and include it in src/viewer/viewer.ts.

In a separate repository

  • Create a repository for your projects.
  • Add TPVector as a submodule, e.g. in the tp-vector subdirectory of your repository.
  • Copy .vscode and deno.jsonc to your repository's root, and make the necessary changes:

    • Add a section to deno.jsonc:

      "imports": {
  "tp-vector/": "./tp-vector/src/",
},

      This will allow referencing the library from your files as:

      import {Piece} from 'tp-vector/index.ts';

    • In .vscode/tasks.json change the esbuild command:

      • Add --alias:tp-vector=./tp-vector/src
      • Change the --outdir and --servedir from src/viewer/static to tp-vector/src/viewer/static.
  • Create a copy of src/viewer/viewer.ts in your own repository and modify it to add your projects.