diff --git a/docs/core-packages-and-features/panes.md b/docs/core-packages-and-features/panes.md index 98ae428..3a94cad 100644 --- a/docs/core-packages-and-features/panes.md +++ b/docs/core-packages-and-features/panes.md @@ -16,3 +16,26 @@ To close a pane, you can close all pane items with Enter. Pulsar runs an indent query on row 1, gets a match for `@indent`, and responds by increasing the indent level on the next line. -* The user types a placeholder comment like `// TODO implement later` and presses Enter again. A query runs against row 2, finds no matches, and therefore decides that row 3 should maintain row 2’s indentation level. -* Finally, the user types `}`. After that keystroke, Pulsar runs an indent query on row 3, finds that the row now starts with a `@dedent` capture, and responds by dedenting row 3 by one level immediately. +* Starting with an empty JavaScript file, a user types `if (foo) {` and presses Enter. Pulsar runs an indent query on row 1, gets a match for `@indent`, and responds by increasing the indent level on row 2. Phase one has increased the indent by one level; since the line has no content, phase two does not alter the indentation level further. +* The user types a placeholder comment like `// TODO implement later`. While the user types, Pulsar checks to see if any of the new content on row 2 should affect its indentation level, but it doesn’t. +* The user presses Enter again. A query runs against row 2, finds no matches, and therefore decides that row 3 should maintain row 2’s indentation level of `1`. +* Finally, the user types `}`. After that keystroke, Pulsar runs an indent query on row 3, finds that the row now starts with a `@dedent` capture, and responds by dedenting row 3 by one level immediately. Phase one produced an indent delta of `0`, but phase two produced a delta of `-1`. Thus you can see that `@indent` means “indent the next line,” while `@dedent` typically means “dedent the current line.” But keep this in mind as well: @@ -610,6 +611,8 @@ For instance, we can handle “hanging” indents like this one… (#is? test.lastTextOnRow)) ``` +(They can also use some specialized tests that apply only to indentation queries: `indent.matchesComparisonRow` an `indent.matchesCurrentRow`. You’ll see an example of this below.) + `@indent` and `@dedent` are often the only captures you need. But for unusual situations, Pulsar allows for other sorts of captures: * `@dedent.next` can be used for the situation where something in row `X` hints that row `X + 1` should be dedented _no matter what_ its content is. @@ -640,13 +643,48 @@ For instance, we can handle “hanging” indents like this one… ```scm ((switch_body "}" @match - (#set! indent.matchIndentOf parent.startPosition))) + (#set! indent.match parent.startPosition))) ``` …because this capture tells Pulsar to set the closing brace’s row to match the indent level of the row where the `switch_body` itself starts. Pulsar therefore sets row 8’s level to match row 1’s. `@match` captures can also define an offset — for scenarios where they want to indent themselves some number of levels _more_ or _less_ than a reference row. + `@match` captures apply to the current row, so they are considered in phase two of indentation hinting. But they end up overriding anything that has happened in phase 1. + +* `@match.next` is the counterpart to `@match`, but it acts in phase one. But it also works like `@dedent.next` in that it allows you to set a “baseline” indentation level for a row without even knowing what its content will be. + + We’ve seen that Pulsar’s default behavior is to maintain the previous row’s indentation level on the next row. But what if you wanted to ignore the previous row’s indentation level in “hanging indent” scenarios? + + ```js + let result = createNewObject("foo", "bar", "baz", "thud", + { save: true, notifyObservers: false }); + ``` + + In this example, the indentation on row 2 is meant to be one-off rather than to set a new level for future lines. When the cursor is at the end of row 2 and we press [[Enter]], we know we should move the indentation level back to `0` on row 3 without even waiting to see what the user types. + + A `@match.next` capture can handle this as follows: + + ```scm + ( + [ + (lexical_declaration) + ; (and other types, but this is a simplified example) + ] @match.next + ; This test means “if the lexical_declaration ends on the comparison row.” + (#if? indent.matchesComparisonRow endPosition) + ; The new row’s indent level should match that of the lexical_declaration’s + ; starting row. + (#set! indent.match startPosition) + ) + ``` + + The logic for resolving a `@match.next` capture is identical to that of resolving a `@match` capture. The differences between them are that + + * a `@match.next` capture works in phase one, not phase two — hence it supersedes other captures that are considered in phase one, like `@indent` and `@dedent.next`; + * unlike `@match`, `@match.next` does not immediately return a result — it instead proceeds to phase two and can still have its suggestion altered by a `@dedent` (or overridden entirely by `@match`). + + Read the full indent query documentation to learn the details. ## Tags @@ -657,7 +695,8 @@ The fourth sort of query file is typically called `tags.scm`, and its purpose is Tree-sitter and other tools call these things “tags,” hence `tags.scm`; but Pulsar calls them “symbols” — hence the {symbols-view} package. ::: -Pulsar’s knowlege of symbols is what allows you to type Cmd+R Ctrl+R and navigate a source code file by function name, or a CSS file by selector, or a Markdown file by heading name. + +Pulsar’s knowlege of symbols is what allows you to type Cmd+RCtrl+R and navigate a source code file by function name, or a CSS file by selector, or a Markdown file by heading name. The `tags.scm` file present in most Tree-sitter repositories goes into a level of detail far greater than what Pulsar needs, but that file will nonetheless work very well as-is, and can almost always be copied directly. diff --git a/docs/developing-for-pulsar/developing-a-theme.md b/docs/developing-for-pulsar/developing-a-theme.md index 04002f1..9c3c4ea 100644 --- a/docs/developing-for-pulsar/developing-a-theme.md +++ b/docs/developing-for-pulsar/developing-a-theme.md @@ -9,7 +9,7 @@ Pulsar supports two types of themes: _UI_ and _Syntax_. UI themes style elements ![Theme boundary](/img/atom/theme-boundary.png) -Themes can be installed and changed from the Settings View which you can open by selecting the _Edit > Preferences_ _Pulsar > Preferences_ _File > Preferences_ menu, and clicking the "Install" or "Themes" tab on the left-hand navigation. +Themes can be installed and changed from the settings view — which you can open by selecting the _Edit > Preferences_ _Pulsar > Preferences_ _File > Preferences_ menu, and clicking the "Install" or "Themes" tab on the left-hand navigation. ## Getting started diff --git a/docs/getting-started/adding-terminal-commands.md b/docs/getting-started/adding-terminal-commands.md deleted file mode 100644 index 1ef80eb..0000000 --- a/docs/getting-started/adding-terminal-commands.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Adding terminal commands -layout: doc.ejs ---- - -Pulsar has support for command-line invocation. For instance, you could `cd` into the directory where your project lives, then run `pulsar .` to open a window for the project. - -It also allows you to manage your installed packages on the command line through a tool called `ppm`, or Pulsar Package Manager. - -Depending on your platform, you might have to perform some steps before these commands will work in your shell. - -## macOS - -On macOS, shell commands won’t be installed automatically, but you can trigger their installation via _Pulsar > Install Shell Commands_. When you select this menu item, `pulsar` and `ppm` are symlinked to `/usr/local/bin`. - -If, after installing shell commands, you can’t get your shell to recognize `pulsar` or `ppm`, inspect your `PATH` environment variable and make sure that `/usr/local/bin` is present. - -## Linux - -### `deb` and `rpm` - -The `deb` and `rpm` distributions of Pulsar will automatically place `pulsar` and `ppm` in your path. - -### `.tar.gz` - -:::danger -_**TODO:** This section is aspirational, since `pulsar.sh` doesn’t yet support invocation from an arbitrary location on disk. On Linux it assumes that Pulsar always lives at `/opt/Pulsar`. This needs changing before these docs will be accurate._ -::: - -If you downloaded the `.tar.gz` version of Pulsar, you’ll find that it decompresses into a folder with a `pulsar` binary at its root. Launching this binary from the terminal will launch Pulsar. - -:::info - -For instance, if you were downloading Pulsar 1.119.0, here’s one strategy you could use: - -* `tar xvzf Linux.pulsar-1.119.0.tar.gz` to extract the downloaded file; -* `mv pulsar-1.119.0 pulsar` to rename the resulting folder; -* `mv pulsar ~/` to move the folder into your user directory - -You could repeat these steps whenever you download a new version of Pulsar, being sure to move or delete the old `~/pulsar` folder first. - -::: - -The proper way to use Pulsar from the shell is via a shell script called `pulsar.sh` that you’ll find inside the `resoures` folder of your extracted download. The `ppm` command exists inside a deeper folder within the tree. - -Once you know where your Pulsar installation will live, you can symlink these scripts into a folder that exists in your `PATH`. - -:::info - -For instance, you could run the following commands to symlink `pulsar` and `ppm` to `/usr/local/bin`: - -``` -ln -s ~/pulsar/resources/pulsar.sh /usr/local/bin/pulsar -ln -s ~/pulsar/resources/app/ppm/bin/ppm /usr/local/bin/ppm -``` - -This assumes `/usr/local/bin` is on your `PATH` and that your Pulsar app lives at `~/pulsar`; you can change the commands accordingly for various origin and destination paths. - -::: - -### AppImage - -The AppImage version of Pulsar works a bit differently. AppImages are self-contained files that can live anywhere on disk, much like macOS applications. To invoke that file in a terminal is equivalent to invoking the `pulsar` executable in other distributions. - -If you’re using an AppImage, here are some suggestions to make it easier to launch Pulsar from the command line: - -* **Rename the download.** When you download the AppImage distribution of Pulsar, the download file will have a name like `Linux.Pulsar.1.XXX.AppImage` (where XXX matches the minor version of the latest Pulsar release). For simplicity’s sake, it’s a good idea to rename this to something shorter, like `Pulsar.AppImage`. This also makes it easier to update Pulsar when new versions come out: rename to `Pulsar.AppImage`, then move it to your destination directory, overwriting the previous version. - -* **Make sure it lives on your `PATH`.** It’s a good idea for your `AppImage` file to live in a directory that’s already on your `PATH` — or to add that directory to your `PATH` if it’s not already present. That allows you to invoke the command from anywhere on your system without specifying its full path. The AppImage documentation has suggestions on [where you could store your AppImages](https://docs.appimage.org/user-guide/faq.html#question-where-do-i-store-my-appimages). - -Launching `ppm` is trickier, since that’s typically its own separate command. But you can instead use the `-p`/`--package` flag when launching Pulsar; when it’s present, the command will be routed to `ppm`. - -If you follow the advice above, you will be able to launch Pulsar and `ppm` as follows: - -* When you see `pulsar` in the docs, replace it with `Pulsar.AppImage`. -* When you see `ppm` in the docs, replace it with `Pulsar.AppImage -p`. - -#### Using aliases for `pulsar` and `ppm` - -But we can go further and use aliases to eliminate the difference altogether: - -* Locate your shell’s startup file, or create one if it’s not present. This might be `.bashrc` or `.bash_profile` if your shell is `bash`, or `.zshrc` if your shell is `zsh`. The startup file typically lives in your home folder. -* Add these lines to your shell startup file: - - ```shell - alias pulsar="Pulsar.AppImage" - alias ppm="Pulsar.AppImage -p" - ``` - -* Restart your shell and make sure your new aliases work: - - ``` - pulsar --version - ppm --version - ``` - - -## Windows - - -:::danger -**TODO:** Certain parts of these instructions won’t work right until [#1054](https://github.com/pulsar-edit/pulsar/pull/1054) is landed. -::: - -Windows installations of Pulsar can attempt to place `pulsar` and `ppm` in your path via the settings. Select _File > Settings_, choose the _System_ pane, and select “Add Pulsar to PATH.” - -If this command runs properly, you should be set — but we’ll make sure in a second. If not, you’ll have to add them manually. - -### Checking your path - -Open a terminal application — Windows Terminal is available for free from the Microsoft Store, or you can use Windows’ built-in PowerShell — and run: - -``` -Get-Command pulsar -Get-Command ppm -``` - -If these commands are identified and point to paths within your Pulsar installation directory, you’re done. If not, keep reading. - -### Manually modifying your path - -:::tip -Before you attempt this, you should remind yourself where you installed Pulsar. If you installed it system-wide, for instance, its installation directory would’ve defaulted to `C:\Program Files\Pulsar`; but if you installed it for just the current user, it would’ve defaulted to `C:\Users\(my-user)\AppData\Local\Programs\pulsar`. - -If you can’t remember where you installed it, check these two locations first. -::: - -Right-click on your Windows start menu and choose _Settings_. In the window that opens, focus the search field, type `environment`, and choose “Edit the system environment variables.” - -![system properties](/img/atom/system-properties.png) - -You’ll be taken to the venerable System Properties dialog. Choose [[Environment Variables…]] and you’ll see a list of defined environment variables for both the user and the system. - -![environment variables](/img/atom/environment-variables-list.png) - -You may edit either your user `Path` or your system `Path`, but most people will probably want to edit their user `Path`. Click on that entry in the list and choose [[Edit…]]. - -You may add new lines to this list. Here’s what you should add: - -* The path to `pulsar.cmd`: `[pulsar-installation-directory]\resources`. -* The path to `ppm.cmd`: `[pulsar-installation-directory]\resources\app\ppm\bin`. - -![system properties](/img/atom/environment-variables.png) - -Click [[OK]] on a few windows until you’re back at the Settings app, then close and reopen your terminal application so that the new `PATH` setting takes effect. Now try [the commands from above](#checking-your-path) again. Both should resolve to paths that match what we put into `PATH` just now. - -The final test is to run them: - -``` -pulsar --version -ppm --version -``` - -Both of these commands should produce output in your terminal. diff --git a/docs/getting-started/dependencies-for-some-community-packages.md b/docs/getting-started/dependencies-for-some-community-packages.md index d5c0708..2c6a404 100644 --- a/docs/getting-started/dependencies-for-some-community-packages.md +++ b/docs/getting-started/dependencies-for-some-community-packages.md @@ -16,18 +16,33 @@ However, some popular packages will involve the use of native modules. Please re Because Pulsar runs on Electron, it is able to use Node modules to complete tasks. Node modules, though written in JavaScript, sometimes also use code written in a lower-level language and bridged to JavaScript. We’ll refer to these as **native modules**. -Pulsar itself uses some native modules, but those modules have been pre-built for your own architecture. But if a _community package_ uses a native module, then it’ll typically need to be built on your system when the package is installed. If an update to Pulsar carries an update to the underlying Electron framework, then those same packages will need to _rebuild_ their native modules to match the new Electron version. +Because native modules are compiled in a language like C++ or Rust, they need to be tailored to your processor architecture, operating system, and version of Node and/or Electron. -For this reason, if you want to install any packages that use native modules, you’ll need local toolchain for building native modules in Node: +If you want to install a _community package_ that uses native modules, this usually requires that you have a local toolchain for building native modules in Node: * A C++ compiler like `gcc` or `clang` * A recent version of [Python](https://www.python.org/) -The good news is that lots of developers will have this toolchain already. For instance, if you’ve already got `npm` installed on your machine and use it occasionally, it is extremely likely that you’ve already got the tools you need. +If not, your computer may require additional setup. -If not, your computer may require additional setup. Choose the section below that corresponds to your operating system. +:::note Why is this necessary? -## Linux +Most of the software you run doesn’t have to be compiled on your machine because some other machine has already compiled it for your architecture. For instance, Pulsar itself uses some native modules, but it “prebuilds” those modules so that they don’t need to be compiled on your machine. So why are community packages different? Shouldn’t those be pre-compiled as well? + +Sometimes they are! Pulsar packages use NPM’s infrastructure. Any dependency that a community package relies on will usually be published to NPM; and NPM allows authors to set up their packages such that, on installation, they’ll try to download a pre-compiled version for the current Node version and architecture instead of compiling the native module locally. + +But there are any number of reasons why this might not happen: + +* Prebuilding requires time and effort on the part of the author and adds complexity to the module; it also requires infrastructure (like GitHub Actions) that, until recently, wasn’t always available for free — even for open source projects. +* When prebuilds are available, they tend to be targeted to the most popular platforms, architectures, and Node versions. For instance, it’s extremely common for a module not to have a prebuild available for _any_ versions of Electron. It’s also common for older modules not to have prebuilds for `arm64` (like Apple Silicon), since it only recently became a popular processor architecture. + +::: + +## Setting up a build toolchain on your platform + +Different operating systems have different toolchains, so choose the section below that corresponds to your operating system. + +### Linux Building native modules for Node on Linux will require `gcc` and `python`. @@ -35,30 +50,28 @@ On Debian/Ubuntu systems, this could be as simple as running `apt install build- It’s extremely likely that your system already has a working version of Python; if not, you can install Python 3 from your distro’s package manager. -You can verify that your system has all the needed tools by running `ppm install --check`. (Depending on how you installed Pulsar, you might need to install shell commands first, as described in the [Adding terminal commands](/getting-started/adding-terminal-commands/#macos) article.) +You can verify that your system has all the needed tools by running `ppm install --check`. (Depending on how you installed Pulsar, you might need to install shell commands first, as described in the [Adding terminal commands](/getting-started/terminal-commands/#macos) article.) -## macOS +If `ppm install --check` produces errors, [visit the section below](#troubleshooting-with-ppm-install---check) to troubleshoot. + +### macOS Building native modules for Node on macOS will require `clang` and `python`. macOS users will be prompted by the system to install Xcode command-line tools the first time they run `git`, `gcc`, or `clang`. You can also run `xcode-select --install` to trigger the prompt. macOS will download and install the tools automatically. **A full installation of Xcode is not necessary.** -You can verify that your system has all the needed tools by running `ppm install --check`. (Be sure to install shell commands first, as described in the [Adding terminal commands](/getting-started/adding-terminal-commands/#macos) article.) +You can verify that your system has all the needed tools by running `ppm install --check`. (Be sure to install shell commands first, as described in the [Adding terminal commands](/getting-started/terminal-commands/#macos) article.) -## Windows +If `ppm install --check` produces errors, [visit the section below](#troubleshooting-with-ppm-install---check) to troubleshoot. -:::danger -**TODO:** Certain parts of these instructions won’t work right until [#1054](https://github.com/pulsar-edit/pulsar/pull/1054) is landed. -::: +### Windows To be able to build native modules on Windows, you'll need to install the following applications: -* Build Tools for Visual Studio (or the Visual Studio IDE) with the **Desktop development with C++** component -* Python 3 (preferably the most recent version) +* **Build Tools for Visual Studio** (or the Visual Studio IDE) with the **Desktop development with C++** component +* **Python 3** (preferably the most recent version) -Full installation instructions follow. - -### Installing Visual Studio Tools +#### Installing Visual Studio Tools :::warning @@ -68,25 +81,28 @@ The instructions below have _nothing to do with_ **Visual Studio Code**. If you You **do not** need a full installation of Visual Studio to be able to compile native Node modules. But you do need some components that must be installed via the Visual Studio installer, so [visit this page](https://visualstudio.microsoft.com/downloads/) and search for **Build Tools for Visual Studio 2022**. You will download an installer pre-configured to install these components. -:::info +You _must_ also select the **Desktop development with C++** component when customizing your installation. This is the component that will allow Node to compile native modules with the `node-gyp` tool. -If you want to install the Visual Studio IDE — or already have it installed — then you can use that _instead of_ Build Tools for Visual Studio, as long as you still install the **Desktop development with C++** component as described below. +![selecting the C++ component](/img/atom/vs-cpp-selected-inset.png) -If you have a pre-existing installation of Visual Studio 2019, or its build tools, that’ll work fine — though you might have to re-run the Visual Studio installer in order to add the **Desktop development with C++** component. +:::info -::: +If you have a pre-existing installation of any of these tools… -You _must_ also select the **Desktop development with C++** component when customizing your installation. These are the components that will allow Node to compile native modules with the `node-gyp` tool. +* Visual Studio 2022 +* Visual Studio 2019 +* Build Tools for Visual Studio 2022 +* Build Tools for Visual Studio 2019 -![selecting the C++ component](/img/atom/vs-cpp-selected-inset.png) +…you do not need to download a new installer. But you may still need to re-run your original installer in order to add the **Desktop development with C++** component. + +If you’re unsure whether the right components are already installed, try `ppm install --check` [as documented below](#troubleshooting-with-ppm-install---check). -:::tip -If you think you might ever want to contribute to Pulsar itself, then this might be a good time to add the **Windows SDK** component, as this is a prerequisite for building Pulsar from source. Most people won’t need this, though! ::: If you didn’t install the right things the first time around, you can re-run the Visual Studio installer and modify your installation. -### Installing Python +#### Installing Python Python can be downloaded from [the Python website](https://www.python.org/downloads/windows/). The latest version of Python 3 is a good choice. @@ -109,15 +125,15 @@ It’s a good idea to select the “Add Python to environment variables” optio Please also note where the installer plans to install Python. You might want to select and copy this value so that you can use it later if you need to help `ppm` find Python. -### Checking your path +#### Checking your path :::warning -At this point, it is assumed that you can invoke `pulsar` and `ppm` from a terminal. If you haven’t done so yet, you should follow the steps in the [Adding terminal commands](/getting-started/adding-terminal-commands/#windows) article. +At this point, it is assumed that you can invoke `pulsar` and `ppm` from a terminal. If you haven’t done so yet, you should follow the steps in the [Adding terminal commands](/getting-started/terminal-commands/#windows) article. ::: -You should also make sure that you have `python` in your path. If you were able to check the “Add python.exe to PATH” box during Python installation, then that should be taken care of, but it’s worth making sure. +You should also make sure that you have `python` in your path. If you were able to check the “Add python.exe to PATH” option during Python installation, then that should be taken care of, but it’s worth making sure. Open your terminal application and run the following command: @@ -131,7 +147,7 @@ You may have to make your window wider just to fit the information. In my case, :::note -If it doesn’t find Python, you’ll have to add some directories to your `PATH`. Follow the directions in the [Adding terminal commands](/getting-started/adding-terminal-commands/#windows) article, but add the following locations to your `PATH` instead: +If it doesn’t find Python, you’ll have to add some directories to your `PATH`. Follow the directions in the [Adding terminal commands](/getting-started/terminal-commands/#windows) article, but add the following locations to your `PATH` instead: * _(the path to your Python installation)_ * _(the path to your Python installation)_`\Scripts` @@ -143,73 +159,158 @@ In my case, these would translate to: ::: -### Running `ppm` to check native module installation - -Since you followed the instructions in [Adding terminal commands](/getting-started/adding-terminal-commands/#windows), you should be able to run `ppm` from your terminal. Try `ppm --version`; it should produce something like this: +### Troubleshooting with `ppm install --check` -![ppm --version](/img/atom/ppm-version-windows.png) +No matter which platform you’re on, you might run into some minor speed bumps when you try to install a package that uses a native module. -At this point, we can use `ppm` itself to help us set up our native module build environment. Run `ppm install --check` to trigger a special behavior from `ppm`: it’ll try to compile a dummy native module, then report any obstacles it encountered. +Luckily, we can use `ppm` itself to help us set up our native module build environment. Run `ppm install --check` to trigger a special behavior from `ppm`: it’ll try to compile a dummy native module, then report any obstacles it encountered. ![ppm install --check](/img/atom/ppm-install-check-windows-success.png) -If `ppm install --check` works and doesn’t raise any errors, you’re done! +If `ppm install --check` works and doesn’t raise any errors, you should be able to install packages with native modules! Otherwise, here are some things to try: #### Install `setuptools` for Python -`ppm` may complain about a lack of `distutils`. That’s something we can fix by installing Python’s `setuptools` package. +`ppm install --check` may complain about a lack of `distutils`. That’s because Python recently stopped including that library by default — but we can fix that by installing Python’s `setuptools` package. + +Installation will vary based on your platform and how you installed Python. + +:::tabs#setuptools -Run this command in your terminal: +@tab Windows + +If you’re a Windows user who installed Python via the instructions above, you can run this command in your terminal: ```powershell pip install setuptools ``` -If it doesn’t know what `pip` is, then your Python path is not set up properly. Hopefully, it’ll succeed at installing `setuptools`, at which point you should run `ppm install --check` again. If it still fails, keep reading. +(If it doesn’t know what `pip` is, then your Python path is not set up properly.) + +@tab macOS + +If you’re a macOS user with Python installed, either `pip` or `pip3` will probably exist in your `PATH`, so you can try `pip install setuptools` (or `pip3 install setuptools`). + +In some cases, though, it might balk at installing packages directly. For instance, if you installed a recent version of Python on macOS via [Homebrew](https://brew.sh/), `pip` might prefer that you run `brew install python-setuptools`. + +@tab Linux + +If you’re a Linux user with Python installed, either `pip` or `pip3` will probably exist in your `PATH`, so you can try `pip install setuptools` (or `pip3 install setuptools`). + +In some cases, though, it might balk at installing packages directly. For instance, if you’re on Debian or Ubuntu and using a system default installation of Python, `pip` will likely tell you that you should install `setuptools` through `apt`. There are packages called `python3-setuptools` and `python3-distutils`, either of which ought to give you what you need: + +```shell +apt install python3-setuptools # or… +apt install python3-distutils +``` + +You may have to add `sudo` to the beginning of either command. + +Other distributions will have [their own package systems](https://wiki.python.org/moin/BeginnersGuide/Download). In general, those distributions will want you to install Python libraries through their own package managers, if possible. Search for a package with `setuptools` or `distutils` in the name; that’s likely to be the one you want. + +::: + +Hopefully, you’ll succeed at installing `setuptools`, at which point you should run `ppm install --check` again. If it still fails, keep reading. #### Tell `ppm` about the path to your version of Python -If `ppm` still complains about missing `distutils` after the step above, or if it thinks you don’t have any build tools installed, it might be using a different version of Python than the one we just installed. +If `ppm` still complains about missing `distutils` after the step above, or if it thinks you don’t have any build tools installed, it might be using a different version of Python than the one you think it’s using. + +Run `ppm --version` again and look at the version of Python it reports: if it’s not the version you had in mind, then we’ll need to tell it how to find your Python installation. + +First, you should find out the path to the `python` executable you want to use. Windows users might have it saved from an earlier step; macOS and Linux users might be able to use `which python` to locate it. -Run `ppm --version` again and look at the version of Python it reports: if it’s not the version you just installed, then we’ll need to tell it how to find your Python installation. +You can tell `ppm` about your Python executable two different ways, but let’s first try this one: -You can tell it about your Python executable two different ways, but let’s first try this one: +:::tabs#locating-python-step-1 + +@tab Windows ```powershell ppm config set python "C:\Users\(my-user)\AppData\Local\Programs\Python\Python312\python.exe" ``` +@tab Linux + +```sh +ppm config set python "/usr/local/bin/python3" # or whatever your path is +``` + +@tab macOS + +```sh +ppm config set python "/usr/local/bin/python3" # or whatever your path is +``` + +::: + + As always, you should make sure this matches the location of your own Python installation. After you run this command, try `ppm --version` again. If it picks up on your new Python version, you’ve succeeded: ![ppm --version](/img/atom/ppm-version-windows.png) -Otherwise, you can try the other way of telling `ppm` about your Python location: the `PYTHON` environment variable. Run this in your terminal, again confirming you’re using the correct path to your own installation of Python: +If not, you can try the other way of telling `ppm` about your Python location: the `PYTHON` environment variable. Run this in your terminal, again confirming you’re using the correct path to your own installation of Python: + +:::tabs#locating-python + +@tab Windows ```powershell $env:Python = "C:\Users\(my-user)\AppData\Local\Programs\Python\Python312\python.exe" ``` +@tab Linux + +```sh +export PYTHON="/usr/local/bin/python3" # or whatever your path is +``` + +@tab macOS + +```sh +export PYTHON="/usr/local/bin/python3" # or whatever your path is +``` + +::: + If `ppm` recognizes your Python version when you run `ppm --version`, you should try running `ppm install --check` again. If it passes, you’ve succeeded! :::tip -If this second technique succeeded, then you’ll want to make sure that `PYTHON` is defined automatically in future shells as well. You can define it using the same process we documented in the earlier [Adding terminal commands](/getting-started/adding-terminal-commands/#windows) article. +If this second technique succeeded, then you’ll want to make sure that `PYTHON` is defined automatically in future shells as well: + +* On macOS or Linux, you can add the line above to a shell startup file like `.bash_profile` or `.zshrc`. +* On Windows, you can define it using the same process we documented in the earlier [Adding terminal commands](/getting-started/terminal-commands/#windows) article. ::: -#### Ensure you installed your Visual Studio tools correctly +#### Ensure you installed your tools correctly + +If `ppm` _still_ thinks you don’t have the right build tools installed, then it’s worth re-checking whether the rest of your compilation toolchain is installed properly. -If `ppm` _still_ thinks you don’t have the right build tools installed, then it’s worth re-checking whether you’ve installed your Visual Studio tools correctly. +:::tabs#double-checking-toolchain + +@tab Windows Re-run the Visual Studio installer and confirm: * You _must_ have **Visual Studio 2022 Build Tools** or **Visual Studio 2019 Build Tools** installed — or the full Visual Studio IDE of either version. * Select whichever one you have installed and click on [[Modify]]. -* You _must_ have “Desktop development with C++” checked. If it is not selected, select it, then click on the [[Modify]] button at the bottom right corner of the window. It will install new components. +* You _must_ have “Desktop development with C++” checked. If it is not selected, select it, then click on the [[Modify]] button at the bottom right corner of the window. It will install new components; wait for the installer to finish before proceeding. + +@tab macOS + +All the tools you need should be provided with Xcode command-line tools, so [revisit the section above](#macos) and double-check that those tools are installed. For instance, `which clang` should resolve to `/usr/bin/clang`, and `clang --version` should output version information. (If it instead prompts you to install something, you didn’t have everything set up yet!) + +@tab Linux + +[Revisit the section above](#linux) and double-check that those tools are installed. You should be able to run `which gcc` (or perhaps `which clang`) and have it locate this tool. + +::: -If you had to make any changes here, wait for the installer to finish, then run `ppm install --check` again. +If you had to make any changes here, run `ppm install --check` again once new tools have been installed. ### Installing a package with a native module @@ -221,6 +322,22 @@ For instance, you can attempt to install `x-terminal-reloaded` either through Pu ppm install x-terminal-reloaded ``` -It’s unlikely, but still possible, that you might run into failures here that you didn’t encounter earlier while running `pulsar install --check`. If so, some of the steps above may still be useful. +It’s unlikely, but still possible, that you might run into failures here that you didn’t encounter earlier while running `ppm install --check`. If so, some of the steps above may still be useful. If you’ve followed the instructions on this page and still can’t get your package to install, join us [on Discord](https://discord.gg/7aEbB9dGRT) or [in GitHub Discussions](https://github.com/orgs/pulsar-edit/discussions) and we’ll try to get you back on track. + + +## Rebuilding packages with native modules + +Since native modules have to be built against a specific version of Node or Electron, they have to be _rebuilt_ whenever that version changes. + +When you upgrade Pulsar, you might occasionaly see an item in your status bar that suggests that some of your packages are incompatible. Pulsar detects this via the built-in {incompatible-packages} package. Clicking on that status item will show you a list of community packages that need addressing. + +![incompatible packages indicator](/img/atom/incompatible-packages-indicator.png) + +When an update results in some of your packages being incompatible, it’s probably because Pulsar updated the version of Electron it uses. There are two common ways of fixing this: + +* The author might already have updated the package, in which case the fix could be as simple as installing the update. +* Otherwise, the way to fix this is to rebuild the native module for the current version of Electron — something that Pulsar should be able to do on its own! To rebuild your packages, click the Rebuild Packages button. + +![incompatible packages UI](/img/atom/incompatible-packages-ui.png) diff --git a/docs/getting-started/getting-started.11tydata.json b/docs/getting-started/getting-started.11tydata.json index 3f4b095..820104f 100644 --- a/docs/getting-started/getting-started.11tydata.json +++ b/docs/getting-started/getting-started.11tydata.json @@ -14,8 +14,8 @@ "summary": "Read setup instructions for all supported platforms." }, { - "text": "Adding terminal commands", - "link": "/getting-started/adding-terminal-commands", + "text": "Launching Pulsar from the terminal", + "link": "/getting-started/terminal-commands", "summary": "Launching Pulsar from the command line." }, { diff --git a/docs/getting-started/terminal-commands.md b/docs/getting-started/terminal-commands.md new file mode 100644 index 0000000..7ffb5dd --- /dev/null +++ b/docs/getting-started/terminal-commands.md @@ -0,0 +1,269 @@ +--- +title: Launching Pulsar from the terminal +layout: doc.ejs +--- + +Pulsar has support for command-line invocation. For instance, you could `cd` into the directory where your project lives, then run `pulsar .` to open a window for the project. + +It also allows you to manage your installed packages on the command line through a tool called `ppm`, or Pulsar Package Manager. + +## About `pulsar` + +:::info +This section assumes that you are able to launch Pulsar from the command line by typing `pulsar` in your terminal. If this isn’t yet true, [read below](#adding-pulsar-and-ppm-to-your-shell) to discover how to enable it for your platform and installation method. +::: + +At its simplest, the `pulsar` command launches Pulsar. But it supports some other features that don’t have obvious analogs in the GUI. + +### Opening a project: `pulsar [path]` + +Opens `[path]` in a new window as its own project. + +### Opening a file: `pulsar [file]` + +Opens `[file]` for editing. + +### Help screen: `pulsar --help` and `pulsar -h` + +Displays a list of all command-line switches, including some too obscure to be covered in this documentation. + +### Version information: `pulsar --version` and `pulsar -v` + +Shows the versions of Pulsar and its dependencies: Node, Chromium, and Electron. + +Each version of Electron is pinned to specific versions of Node and Chromium. If you’re working on a Pulsar package, you might find it useful to know the Node and Chromium versions, since that tells you which APIs are available to you. + +### Wait mode: `pulsar --wait [file]` and `pulsar -w [file]` + +Opens `[file]` for editing, waiting until the file is closed before exiting. + +When GUI apps like Pulsar are launched from the terminal, it’s typically a good idea for the terminal not to “wait” for the app to quit. As a user, you probably expect your terminal to offer you a new prompt after the app has spawned. So that’s what Pulsar does by default. + +But if you want to use Pulsar for Git-related tasks like interactive rebases and commit message editing, you need it to behave differently — “blocking” while a specific file is being edited. + +That’s the purpose of `--wait` and `-w`: when called with a specific file path, Pulsar will open that path for editing, then wait until it is no longer active in the workspace before exiting the terminal script that launched Pulsar. + +If you want to use Pulsar as an editor for Git commits, interactive rebases, and such, you should add one of these lines to your shell startup script: + +```shell +# Either of these lines will work on macOS or Linux. +export EDITOR="pulsar -w" +export GIT_EDITOR="pulsar -w" + +# This line will work on all platforms. +git config core.editor "pulsar -w" +``` + +### Safe mode: `pulsar --safe` + +Including `--safe` with any usage of `pulsar` will open Pulsar in “safe mode”: no packages will be loaded from the user’s home directory. Only built-in packages will be loaded. + +If you think Pulsar might have a bug, safe mode is a useful way to determine whether the unwanted behavior is coming from Pulsar or from a community package you might have installed. + +### Adding to a project: `pulsar --add [path]` and `pulsar -a [path]` + +Pulsar projects can have more than one root path. Adding the `-a`/`--add` switch to this command will open `[path]` in the most-recently-used window instead of opening a new one. + +### Dev mode: `pulsar --dev [path]` + +Opens a new window in “development mode” for `[path]`. + +_Development mode_ is a special mode of Pulsar that is useful for developing Pulsar packages or for contributing to Pulsar itself. See [Running in development mode](/contributing-to-pulsar/hacking-on-the-core/#running-in-development-mode) to read more about it. + +### Proxying to `ppm`: `pulsar --package [args]` and `pulsar -p [args]` + +Collects all arguments immediately after `-p`/`--package` and passes them to `ppm`, ignoring any earlier arguments. + +`pulsar -p [args]` is thus equivalent to `ppm [args]` in all scenarios. + +The `-p`/`--package` switch is most useful for AppImage installations, but you might want to use `pulsar -p` instead of `ppm` for your own reasons as well. + +## About `ppm` + +`ppm` stands for _Pulsar Package Manager_. It’s a Pulsar-branded version of [`npm`](https://web.pulsar-edit.dev/) that installs packages from Pulsar’s own [package registry](https://web.pulsar-edit.dev/). + +It’ll be covered in greater depth later; just know that it’s a way to install Pulsar packages from the command line, and it works whether or not Pulsar is running. + +## Adding `pulsar` and `ppm` to your shell + +On some platforms, `pulsar` and `ppm` will be immediately available to you after installation. On others, you might have to perform some steps before these commands will work in your shell. + +### macOS + +On macOS, shell commands won’t be installed automatically, but you can trigger their installation via _Pulsar > Install Shell Commands_. When you select this menu item, `pulsar` and `ppm` are symlinked to `/usr/local/bin`. + +If, after installing shell commands, you can’t get your shell to recognize `pulsar` or `ppm`, inspect your `PATH` environment variable and make sure that `/usr/local/bin` is present. + +### Linux + +#### `deb` and `rpm` installations + +The `deb` and `rpm` distributions of Pulsar will automatically place `pulsar` and `ppm` in your path. + +#### `.tar.gz` installation + +If you downloaded the `.tar.gz` version of Pulsar, you’ll find that it decompresses into a folder with a `pulsar` binary at its root. Launching this binary from the terminal will launch Pulsar. + +:::info Updating the tar.gz distribution + +To make updates easier, we recommend that you store Pulsar at a **consistent location on disk** that does not change between versions. + + +For instance, if you were downloading Pulsar 1.119.0, here’s one strategy you could use: + +* `tar xvzf Linux.pulsar-1.119.0.tar.gz` to extract the downloaded file; +* `mv pulsar-1.119.0 pulsar` to rename the resulting folder; +* `mv pulsar ~/` to move the folder into your user directory. + +You could repeat these steps whenever you download a new version of Pulsar, being sure to move or delete the old `~/pulsar` folder first. + +::: + +The proper way to use Pulsar from the shell is via a shell script called `pulsar.sh` that you’ll find inside the `resources` folder of your extracted download. The `ppm` command exists inside a deeper folder within the tree. + +Once you know where your Pulsar installation will live, you can symlink these scripts into a folder that exists in your `PATH`. + +:::info + +For instance, you could run the following commands to symlink `pulsar` and `ppm` to `/usr/local/bin`: + +``` +ln -s ~/pulsar/resources/pulsar.sh /usr/local/bin/pulsar +ln -s ~/pulsar/resources/app/ppm/bin/ppm /usr/local/bin/ppm +``` + +This assumes `/usr/local/bin` is on your `PATH` and that your Pulsar app lives at `~/pulsar`; you can change the commands accordingly for various origin and destination paths. + +If you follow the advice above and keep Pulsar installed at a consistent path across updates, these symlinks will keep working even when you upgrade Pulsar to a newer version. + +::: + +#### AppImage installation + +The AppImage version of Pulsar works a bit differently. [AppImages](https://en.wikipedia.org/wiki/AppImage) are entire applications contained in a single file that can live anywhere on disk, much like macOS applications. + +When you invoke the Pulsar AppImage file in a terminal, Pulsar executes the same launcher script that is symlinked by the DEB and RPM installations. + +For instance, here are some commands you might see in the documentation, and their equivalents for the AppImage distribution (assuming your installation is called `Pulsar.AppImage` and lives in a directory on your `PATH`): + +* `Pulsar.AppImage --version` is equivalent to running `pulsar --version` (show Pulsar’s version) +* `Pulsar.AppImage --wait foo.txt` is equivalent to running `pulsar --wait foo.txt` (open `foo.txt` for editing and wait until that file is closed) +* `Pulsar.AppImage --dev path/to/project` is equivalent to running `pulsar --dev path/to/project` (open a certain path as a new project in dev mode) + +If you’re using an AppImage, here are some suggestions to make it easier to launch Pulsar from the command line: + +* **Rename the download.** When you download the AppImage distribution of Pulsar, the download file will have a name like `Linux.Pulsar.1.XXX.AppImage` (where XXX matches the minor version of the latest Pulsar release). For simplicity’s sake, it’s a good idea to rename this to something **short and consistent**, like `Pulsar.AppImage`. + + Ideally, your Pulsar AppImage should be named the same thing on disk no matter which version of Pulsar you’re running. This makes it easier to update Pulsar when new versions come out: rename to `Pulsar.AppImage`, then move it to your destination directory, overwriting the previous version. + +* **Make sure it lives on your `PATH`.** It’s a good idea for your `AppImage` file to live in a directory that’s already on your `PATH` — or to add that directory to your `PATH` if it’s not already present. That allows you to invoke the command from anywhere on your system without specifying its full path. + + The AppImage documentation has suggestions on [where you could store your AppImages](https://docs.appimage.org/user-guide/faq.html#question-where-do-i-store-my-appimages). Your own distribution may have its own recommended conventions for placement or management of AppImages. + +* **Use aliases for speed.** If you’ve followed the steps above, you’ll be able to type `Pulsar.AppImage` no matter which directory you’re in. But you can simplify it further by [defining an alias](#using-aliases-for-pulsar-and-ppm) as described below. + +##### Handling `ppm` + +So it’s easy to run Pulsar itself as an AppImage — but `ppm` isn’t so straightforward, since an AppImage has only one entry point. + +That’s why Pulsar supports a `--package` flag (or `-p` for short) that “proxies” to `ppm`. For instance: + +* `Pulsar.AppImage --package --version` is equivalent to `ppm --version` +* `Pulsar.AppImage -p install linter` is equivalent to `ppm install linter` + +If the `-p`/`--package` flag is present when running `Pulsar.AppImage`, all arguments before that flag will be ignored, and all arguments after that flag will be passed to `ppm` in order. + +If you follow the advice above, you will be able to launch Pulsar and `ppm` as follows: + +* When you see `pulsar` in the docs, replace it with `Pulsar.AppImage`. +* When you see `ppm` in the docs, replace it with `Pulsar.AppImage -p`. + +##### Using aliases for `pulsar` and `ppm` + +But we can go further and use aliases to eliminate the difference altogether: + +* Locate your shell’s startup file, or create one if it’s not present. This might be `.bashrc` or `.bash_profile` if your shell is `bash`, or `.zshrc` if your shell is `zsh`. The startup file typically lives in your home folder. + +* Add these lines to your shell startup file: + + ```shell + alias pulsar="Pulsar.AppImage" + alias ppm="Pulsar.AppImage -p" + ``` + +* Restart your shell and make sure your new aliases work: + + ``` + pulsar --version + ppm --version + ``` + + +### Windows + +#### Standard installation + +The standard Windows installation of Pulsar allows the user to add `pulsar` and `ppm` to their `PATH`; both options are enabled by default during the setup wizard. + +![system properties](/img/atom/windows-setup-step-3.png) + +:::tip +Before version 1.121.0, Pulsar didn’t offer to place these commands in your `PATH`. If you’re on an earlier version, either update to the latest version of Pulsar (in which case you’ll be able to opt into it during setup) or follow the directions below for portable installations of Windows. +::: + +If you want to change this setting, you can run your Pulsar setup file again. + +#### Portable installation and manual modification + +The “portable” version of Pulsar for Windows does not use an installer; you can put it anywhere you like on your system and create a shortcut to `Pulsar.exe`. + +For this reason, you’ll have to add `pulsar` and `ppm` to your `PATH` manually. The instructions below also apply for anyone who wants to add the Pulsar directories to their `PATH` manually (or remove them manually). + +##### First: note where Pulsar is located + +On a portable installation, this is a directory of your choice. Note the root directory of your Pulsar installation; consider copying it to the clipboard or saving it in a temporary text file. + +If you installed Pulsar traditionally, this will default to `C:\Users\(my-user)\AppData\Local\Programs\pulsar` (if you installed for just the current user) or `C:\Program Files\Pulsar` (if you installed for all users). + +##### Edit your `PATH` manually + +Right-click on your Windows start menu and choose _Settings_. In the window that opens, focus the search field, type `environment`, and choose “Edit the system environment variables.” + +![system properties](/img/atom/system-properties.png) + +You’ll be taken to the venerable System Properties dialog. Choose [[Environment Variables…]] and you’ll see a list of defined environment variables for both the user and the system. + +![environment variables](/img/atom/environment-variables-list.png) + +You may edit either your user `Path` or your system `Path`, but most people will probably want to edit their user `Path`. Click on that entry in the list and choose [[Edit…]]. + +You’ll see a new window with a list of paths to directories on disk. You may add new lines to this list. Here’s what you should add… + +* The path to `pulsar.cmd`: `[pulsar-installation-directory]\resources`. +* The path to `ppm.cmd`: `[pulsar-installation-directory]\resources\app\ppm\bin`. + +…replacing `[pulsar-installation-directory]` with the directory into which you installed Pulsar. + +![system properties](/img/atom/environment-variables.png) + +Click [[OK]] on a few windows until you’re back at the Settings app, then close and reopen your terminal application so that the new `PATH` setting takes effect. Now we’ll see if it worked. + +#### Testing `pulsar` and `ppm` on Windows + +Open a terminal application — [Windows Terminal](https://aka.ms/terminal) is available for free from the Microsoft Store, or you can use Windows’ built-in PowerShell — and run: + +``` +Get-Command pulsar +Get-Command ppm +``` + +If these commands are identified and point to paths within your Pulsar installation directory, you’ve succeeded. + +The final test is to run them: + +``` +pulsar --version +ppm --version +``` + +Both of these commands should produce output in your terminal. diff --git a/docs/infrastructure/keymaps-in-depth.md b/docs/infrastructure/keymaps-in-depth.md index d625447..f78dadd 100644 --- a/docs/infrastructure/keymaps-in-depth.md +++ b/docs/infrastructure/keymaps-in-depth.md @@ -120,7 +120,7 @@ Currently, there's no way to specify selector ordering within a single keymap, b For instance, the {snippets} package defines two keymap files: `snippets-1.cson` and `snippets-2.cson`. It does this because it binds two different commands to the [[Tab]] key, and it’s critical that one of those bindings is processed before the other. -### Selectors and custom packages +### Targeting specific grammars If a keybinding should only apply to a specific grammar, you can limit bindings to that grammar using the `data-grammar` attribute on the `atom-text-editor` element: diff --git a/docs/using-pulsar/basics.md b/docs/using-pulsar/basics.md index 6e12cba..73eae1e 100644 --- a/docs/using-pulsar/basics.md +++ b/docs/using-pulsar/basics.md @@ -295,7 +295,7 @@ When viewed in the GUI with `settings-view`, however, names of settings are made ## Proxy and Firewall Settings -#### Behind a Firewall? +### Behind a Firewall? If you are behind a firewall and seeing SSL errors when installing packages, you can disable strict SSL by running: @@ -303,7 +303,7 @@ If you are behind a firewall and seeing SSL errors when installing packages, you $ pulsar -p config set strict-ssl false ``` -#### Using a Proxy? +### Using a Proxy? If you are using a HTTP(S) proxy, you can configure `ppm` to use it by running: diff --git a/img/atom/incompatible-packages-ui.png b/img/atom/incompatible-packages-ui.png new file mode 100644 index 0000000..81fa4d3 Binary files /dev/null and b/img/atom/incompatible-packages-ui.png differ diff --git a/img/atom/windows-setup-step-3.png b/img/atom/windows-setup-step-3.png new file mode 100644 index 0000000..eebbf32 Binary files /dev/null and b/img/atom/windows-setup-step-3.png differ diff --git a/submodules/dot-github b/submodules/dot-github index 1d7c3dd..5e21873 160000 --- a/submodules/dot-github +++ b/submodules/dot-github @@ -1 +1 @@ -Subproject commit 1d7c3ddb51cc428c570ea5ad872304502a3fb145 +Subproject commit 5e218738cb13511fde1b46a3a626cef58d5fe3cf diff --git a/submodules/pulsar b/submodules/pulsar index 3411fb7..38c0b88 160000 --- a/submodules/pulsar +++ b/submodules/pulsar @@ -1 +1 @@ -Subproject commit 3411fb731a54a6c4454fc4f4716b86fb28133805 +Subproject commit 38c0b8837f9c2b43df2846d809ef5bbab0f46a9d