|
1 | | -## Table of Contents |
| 1 | +## TODO |
2 | 2 |
|
3 | | -1. [About the Project](#about-the-project) |
4 | | -1. [Questions and Help](#questions-and-help) |
5 | | -1. [Getting Started](#getting-started) |
6 | | -1. [Modules and Patterns](#modules-and-patterns) |
7 | | -1. [Useful Resources](#useful-resources) |
8 | | - |
9 | | -# About the Project |
10 | | - |
11 | | -The VSCode extension is written in TypeScript with C# being used for the language server and debug proxy. |
12 | | - |
13 | | -Uses the **[Papyrus Debug Adapter](https://github.com/joelday/papyrus-debug-server) xSE plugin** for live debugging. |
14 | | - |
15 | | -Also uses [this fork of **Pyro**](https://github.com/rjstone/pyro) for PPJ builds. |
16 | | - |
17 | | -# Questions and Help |
18 | | - |
19 | | -Do you have questions or need help? Please come visit the.... |
20 | | - |
21 | | -[ Papyrus Language Tools Discord](https://discord.gg/E4dWujQ) |
22 | | - |
23 | | -Even if you don't plan to contribute code, it would be good to hear how you are using the extension and get your feedback. |
24 | | - |
25 | | -# Getting Started |
26 | | - |
27 | | -## Building |
28 | | - |
29 | | -First, you will need Windows with the following installed on your system: |
30 | | - |
31 | | -- VSCode [Download and install](https://code.visualstudio.com/) |
32 | | -- Node.js [Download and install](https://nodejs.org/) |
33 | | -- Git for Windows [Download and install](https://git-scm.com/download/win) |
34 | | -- One of the following: |
35 | | - - Minimum: .NET Core 2.1 SDK [Download and install](https://dotnet.microsoft.com/download/dotnet-core) |
36 | | - - Recommended: Microsoft Visual Studio 2019 [Download and install](https://visualstudio.microsoft.com/vs/) |
37 | | - |
38 | | -Also, building from the shell will be much easier if you use a **Powershell** (powershell.exe) console because the main build script is written in PS, but if you have Visual Studio installed you should be able to build from the solution file. |
39 | | - |
40 | | -### 1 |
41 | | - |
42 | | -First, Fork the `joelday/papyrus-lang` repo on github. Then clone it: |
43 | | - |
44 | | -```powershell |
45 | | -git clone https://github.com/<yourusername>/papyrus-lang.git |
46 | | -cd papyrus-lang |
47 | | -``` |
48 | | - |
49 | | -### 2 |
50 | | - |
51 | | -Create a branch for your new development: |
52 | | - |
53 | | -```powershell |
54 | | -git checkout -b mynewfeature |
55 | | -``` |
56 | | - |
57 | | -### 3 |
58 | | - |
59 | | -Set your upstream remote to help you pull changes from main when needed: |
60 | | - |
61 | | -```powershell |
62 | | -git remote add upstream https://github.com/joelday/papyrus-lang.git |
63 | | -``` |
64 | | - |
65 | | -### 4 |
66 | | - |
67 | | -Make sure your script execution policy allows running unsigned scripts as long as they're already on disk and not executed from the internet: |
68 | | - |
69 | | -```powershell |
70 | | -Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser |
71 | | -Get-ExecutionPolicy -List |
72 | | -``` |
73 | | - |
74 | | -### 5 |
75 | | - |
76 | | -Run the build script with default targets: |
77 | | - |
78 | | -```powershell |
79 | | -.\build.ps1 |
80 | | -``` |
81 | | - |
82 | | -In the same directory, run this to update the bundled third-party packages (which are provided by separate repos): |
83 | | - |
84 | | -```powershell |
85 | | -.\build.ps1 -Script build.cake -Target update-debug-plugin |
86 | | -.\build.ps1 -Script build.cake -Target update-pyro-cli |
87 | | -``` |
88 | | - |
89 | | -### 6 |
90 | | - |
91 | | -Run VSCode to open the papyrus-lang directory as a folder. If this is still your current directory then just run: |
92 | | - |
93 | | -```powershell |
94 | | -code . |
95 | | -``` |
96 | | - |
97 | | -Hit **Ctrl-Shift-D** to open the Debug panel. At the top select **Launch (Build Extension Only)**. |
98 | | - |
99 | | -Hit **F5** to build and launch the extension with debugging. After a little while you will see another VSCode window open. This is the Extension Development Host version of VSCode running the extension that was just built. Any changes you made to the code would be reflected in the debug/test install of the extension running in this window. |
100 | | - |
101 | | -### 7 |
102 | | - |
103 | | -It is not required that you squash your commits before submitting a pull request, so just commit and push your changes to your fork, then submit the pull request for your branch. Please merge from `upstream/master` to your branch before submitting the pull request though to make sure your changes will merge. |
104 | | - |
105 | | -```powershell |
106 | | -git merge upstream/main |
107 | | -``` |
108 | | - |
109 | | -# Modules and Patterns |
110 | | - |
111 | | -This is a brief set of links to more info on modules and patterns used in the code. |
112 | | - |
113 | | -- [decoration-ioc](https://github.com/joelday/decoration-ioc) is why `InstantiationService` is used to instantiate services and command handlers based on the Service Locator design pattern. It makes it easy to add references to services in the constructor of a class. For example just put `@IExtensionConfigProvider infoProvider: IExtensionConfigProvider` in the argument list of a constructor and it will magically get called with a reference. |
114 | | -- For a simple example of how to add a command, see `src\papyrus-lang-vscode\src\features\commands\ViewAssemblyCommand.ts` |
115 | | -- [rxjs](https://www.npmjs.com/package/rxjs) is used in many places for the reactive Observer/Observable asynchronous pattern. |
116 | | -- [async/await](https://javascript.info/async-await) is used frequently. If possible try to use async functions and `await` on them because this allows other things to happen while a function is blocked on IO etc. |
117 | | -- [deepmerge](https://www.npmjs.com/package/deepmerge) is used in some places. |
118 | | -- Otherwise most of the code is similar to other vscode extensions. |
119 | | - |
120 | | -# Useful Resources |
121 | | - |
122 | | -- See the [Project Wiki](https://github.com/joelday/papyrus-lang/wiki) |
123 | | -- [The Typescript Programming Language Documentation](https://www.typescriptlang.org/docs/home.html) |
124 | | -- [VSCode Extension Anatomy](https://code.visualstudio.com/api/get-started/extension-anatomy) |
125 | | -- [VSCode Extension Samples](https://github.com/microsoft/vscode-extension-samples) are useful for learning specific APIs |
126 | | -- [Learn RxJS](https://www.learnrxjs.io/) (Reactive eXtensions for Javascript) |
127 | | -- [JavaScript Promises](https://javascript.info/async) |
128 | | -- The [Pro Git](https://git-scm.com/book/en/v2/) book |
129 | | -- The [Contributing](https://github.com/joelday/papyrus-lang/wiki/Contributing) wiki page |
| 3 | +Removing for now since the previous version was very out of date. |
0 commit comments