diff --git a/package.json b/package.json index fd15b68..8694aad 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,8 @@ "onView:electron-build-tools:configs", "onView:electron-build-tools:patches", "onView:electron-build-tools:docs", - "onView:electron-build-tools:electron" + "onView:electron-build-tools:electron", + "onWalkthrough:electron-build-tools" ], "categories": [ "Extension Packs", @@ -82,6 +83,12 @@ "category": "Electron Build Tools", "enablement": "electron-build-tools:active && electron-build-tools:canBuild" }, + { + "command": "electron-build-tools.installBuildTools", + "title": "Install Build Tools", + "category": "Electron Build Tools", + "enablement": "!electron-build-tools:build-tools-installed" + }, { "command": "electron-build-tools.newConfig", "title": "New Config", @@ -94,6 +101,11 @@ "title": "Open Patch", "category": "Electron Build Tools" }, + { + "command": "electron-build-tools.openWalkthrough", + "title": "Open Walkthrough", + "category": "Electron Build Tools" + }, { "command": "electron-build-tools.refreshPatches", "title": "Refresh Patches", @@ -326,10 +338,18 @@ "command": "electron-build-tools.buildAdvanced", "when": "electron-build-tools:build-tools-installed" }, + { + "command": "electron-build-tools.installBuildTools", + "when": "false" + }, { "command": "electron-build-tools.openPatch", "when": "false" }, + { + "command": "electron-build-tools.openWalkthrough", + "when": "false" + }, { "command": "electron-build-tools.removeConfig", "when": "false" @@ -572,12 +592,91 @@ "viewsWelcome": [ { "view": "electron-build-tools:welcome", - "contents": "In order to use the Electron Build Tools extension, you need the npm package @electron/build-tools, version 1.1.0 or newer, installed." + "contents": "In order to use the Electron Build Tools extension, you need the npm package @electron/build-tools, version 1.1.0 or newer, installed.\n[Open Walkthrough](command:electron-build-tools.openWalkthrough)" }, { "view": "electron-build-tools:workspace", "contents": "An Electron checkout wasn't found in this workspace.\n[Open Folder](command:vscode.openFolder)" } + ], + "walkthroughs": [ + { + "id": "electron-build-tools", + "title": "Get Started with Electron Build Tools", + "description": "Learn about Electron Build Tools and the Electron Build Tools extension for VS Code", + "featuredFor": [ + "ELECTRON_VERSION", + "src/ELECTRON_VERSION" + ], + "steps": [ + { + "id": "electron-build-tools.install", + "title": "Install Electron Build Tools", + "description": "Install the ``@electron/build-tools`` npm package.\n[Install Electron Build Tools](command:electron-build-tools.installBuildTools)", + "media": { + "markdown": "resources/walkthrough/install-build-tools.md" + }, + "completionEvents": [ + "onContext:electron-build-tools:build-tools-installed" + ] + }, + { + "id": "electron-build-tools.create-config", + "title": "Create a Build Tools config", + "description": "Create a config to start building Electron.\n[Create Config](command:electron-build-tools.newConfig)", + "media": { + "markdown": "resources/walkthrough/config.md" + }, + "completionEvents": [ + "onContext:electron-build-tools:active-config" + ] + }, + { + "id": "electron-build-tools.sync", + "title": "Sync the Electron checkout", + "description": "The initial sync will download the source code and sync dependencies.\n[Sync](command:electron-build-tools.sync)", + "media": { + "markdown": "resources/walkthrough/sync-command.md" + }, + "completionEvents": [ + "onCommand:electron-build-tools.sync" + ] + }, + { + "id": "electron-build-tools.open-workspace", + "title": "Open the Electron checkout", + "description": "Open the Electron checkout in the workspace to get started with Electron Build Tools extension features.\nThis can either be at the root level, ``src``, or in the Electron subfolder, ``src/electron``.\n[Open Folder](command:vscode.openFolder)", + "media": { + "markdown": "resources/walkthrough/empty.md" + }, + "completionEvents": [ + "onContext:electron-build-tools:is-electron-workspace" + ] + }, + { + "id": "electron-build-tools.build", + "title": "Build Electron", + "description": "Build Electron from source.\n[Build](command:electron-build-tools.build)", + "media": { + "markdown": "resources/walkthrough/build.md" + }, + "completionEvents": [ + "onCommand:electron-build-tools.build" + ] + }, + { + "id": "electron-build-tools.learn-more", + "title": "Learn more", + "description": "🎨 Explore all the features the Electron Build Tools extension has to offer by looking for \"Electron Build Tools\" in the [Command Palette](command:workbench.action.showCommands).\n ✨ Take a look at the [Changelog](https://marketplace.visualstudio.com/items/dsanders11.vscode-electron-build-tools/changelog) to learn more about the latest features. \n \n[Learn More](https://github.com/dsanders11/vscode-electron-build-tools)", + "media": { + "markdown": "resources/walkthrough/empty.md" + }, + "completionEvents": [ + "onStepSelected" + ] + } + ] + } ] }, "extensionPack": [ diff --git a/resources/walkthrough/build.md b/resources/walkthrough/build.md new file mode 100644 index 0000000..5969558 --- /dev/null +++ b/resources/walkthrough/build.md @@ -0,0 +1,3 @@ +# Build Electron + +TODO diff --git a/resources/walkthrough/config.md b/resources/walkthrough/config.md new file mode 100644 index 0000000..d5859c2 --- /dev/null +++ b/resources/walkthrough/config.md @@ -0,0 +1,14 @@ +# Build Tools Config + +Build configs define the build configuration, e.g. the path to the source +code, compile-time options, your GitHub fork, and so on. + +Each build config has a unique name, chosen by you to use as a mnemonic when +switching between build configs. This is the name's only purpose, so choose +whatever you find easiest to work with - whether it's `electron`, +`6-1-x--testing`, or `chocolate-onion-popsicle`. + +Each build also needs a root directory. All the source code and built files +will be stored somewhere beneath it. If you want to make multiple build types +of the same branch, you can reuse an existing root to share it between build +configs. diff --git a/resources/walkthrough/empty.md b/resources/walkthrough/empty.md new file mode 100644 index 0000000..e69de29 diff --git a/resources/walkthrough/install-build-tools.md b/resources/walkthrough/install-build-tools.md new file mode 100644 index 0000000..e79982a --- /dev/null +++ b/resources/walkthrough/install-build-tools.md @@ -0,0 +1,41 @@ +# Electron Build Tools + +## What Is It? + +Electron Build Tools is a command-line interface (CLI) to help build Electron +from source, and has other helper commands for common development tasks. This +VS Code extension provides a deep integration of Electron's build tools into +VS Code, providing a graphical user interface (GUI) for the most common +commands, user-friendly views of tests and patches, and other handy helpers. + +You can learn more about the Electron Build Tools CLI +[here](https://github.com/electron/build-tools). + +## Prerequisites + +A handful of prerequisites, such as Git, Node.js, and npm, are required for +building Electron itself; these can be found in [Platform Prerequisites]. + +Electron Build Tools is configured to use Yarn, so please +[install it to your system](https://yarnpkg.com/lang/en/docs/install/). + +## Installing + +For convenience, you can use the "Install Build Tools" button on this step +to install the `@electron/build-tools` package for you. + +If you want to manually install it, from here on you'll need a command-line +prompt. On Mac and Linux, this will be a terminal with a shell, e.g. bash or +zsh. You can also use these on Windows if you install them, or use built-in +tools like Windows' [Command Prompt]. + +Please note that build tools (due to nested dependencies) might not work +properly in powershell, please use `cmd` on Windows for optimum results. + +```sh +# Install build-tools package globally: +yarn global add @electron/build-tools +``` + +[Command Prompt]: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands#command-shell-overview +[Platform Prerequisites]: https://electronjs.org/docs/development/build-instructions-gn#platform-prerequisites diff --git a/resources/walkthrough/sync-command.md b/resources/walkthrough/sync-command.md new file mode 100644 index 0000000..9573d3d --- /dev/null +++ b/resources/walkthrough/sync-command.md @@ -0,0 +1,34 @@ +# The Sync Command + +## Initial Sync + +Getting the source code is a lot more than cloning `electron/electron`. +Electron is built on top of Chromium (with Electron patches) and Node +(with more Electron patches). A source tree needs to have all of the +above **and** for their versions to be in sync with each other. Electron +uses Chromium's [Depot Tools] and [GN] for wrangling and building the code. + +After creating a new config, the initial sync will perform all of these steps +and get the Electron checkout ready for building. It will take a while to +download everything and initialize it, potentially hours depending on your +internet speed, so you might want to take a caffeine break after kicking it +off. There's a handy progress bar to let you know how things are going: + +TODO: Insert picture of progress bar. + +## When To Use Sync + +TODO: + +* When switching branches + +## Force Sync + +An interrupted sync may leave the source tree in a bad state which will cause +future syncs to fail. To remedy this situation, you can run a force sync which +will clean up the state of the source tree before syncing. + +TODO: Insert picture of force sync in command palette + +[Depot Tools]: https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up +[GN]: https://chromium.googlesource.com/chromium/src/tools/gn/+/48062805e19b4697c5fbd926dc649c78b6aaa138/README.md diff --git a/src/extension.ts b/src/extension.ts index ff9eca5..589fc7a 100644 --- a/src/extension.ts +++ b/src/extension.ts @@ -28,6 +28,7 @@ import { drillDown, findElectronRoot, getPatchesConfigFile, + installBuildTools, isBuildToolsInstalled, OptionalFeature, setContext, @@ -172,7 +173,40 @@ export async function activate(context: vscode.ExtensionContext) { vscode.window.registerTreeDataProvider( viewIds.HELP, new HelpTreeDataProvider(context.extensionUri) - ) + ), + vscode.commands.registerCommand( + `${commandPrefix}.installBuildTools`, + async () => { + vscode.window.withProgress( + { + location: vscode.ProgressLocation.Notification, + title: "Installing Electron Build Tools", + cancellable: true, + }, + async (progress, token) => { + const success = await installBuildTools(token); + + if (success !== undefined) { + if (success) { + vscode.window.showInformationMessage( + "Successfully installed Electron Build Tools" + ); + } else { + vscode.window.showErrorMessage( + "Failed to install Electron Build Tools" + ); + } + } + } + ); + } + ), + vscode.commands.registerCommand(`${commandPrefix}.openWalkthrough`, () => { + return vscode.commands.executeCommand( + "workbench.action.openWalkthrough", + "dsanders11.vscode-electron-build-tools#electron-build-tools" + ); + }) ); const workspaceFolders = vscode.workspace.workspaceFolders; diff --git a/src/utils.ts b/src/utils.ts index 4ea3e67..de6d79b 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -666,3 +666,39 @@ export function positionAt(content: string, offset: number) { return new vscode.Position(lines.length - 1, lastLine.length); } + +export async function installBuildTools(token: vscode.CancellationToken) { + const task = new vscode.Task( + { type: "electron-build-tools", task: "install-build-tools" }, + vscode.TaskScope.Workspace, + "Install Build Tools", + "electron-build-tools", + new vscode.ProcessExecution("yarn", [ + "global", + "add", + "@electron/build-tools", + ]) + ); + task.presentationOptions = { + reveal: vscode.TaskRevealKind.Silent, + echo: true, + clear: true, + }; + + const disposables: vscode.Disposable[] = []; + + return new Promise(async (resolve) => { + vscode.tasks.onDidEndTaskProcess(({ execution, exitCode }) => { + if (execution === taskExecution) { + resolve(exitCode ? exitCode === 0 : undefined); + disposables.forEach((disposable) => disposable.dispose()); + } + }, disposables); + + const taskExecution = await vscode.tasks.executeTask(task); + + token.onCancellationRequested(() => { + taskExecution.terminate(); + }, disposables); + }); +} diff --git a/src/views/help.ts b/src/views/help.ts index f6a648e..d847989 100644 --- a/src/views/help.ts +++ b/src/views/help.ts @@ -1,6 +1,11 @@ import * as vscode from "vscode"; -import { buildToolsRepository, extensionId, repositoryUrl } from "../constants"; +import { + buildToolsRepository, + commandPrefix, + extensionId, + repositoryUrl, +} from "../constants"; export class HelpTreeDataProvider implements vscode.TreeDataProvider @@ -26,6 +31,16 @@ export class HelpTreeDataProvider title: "Report Issue", }; + const walkthroughTreeItem = new vscode.TreeItem( + "Open Extension Walkthrough", + vscode.TreeItemCollapsibleState.None + ); + walkthroughTreeItem.iconPath = new vscode.ThemeIcon("extensions"); + walkthroughTreeItem.command = { + command: `${commandPrefix}.openWalkthrough`, + title: "Open Walkthrough", + }; + return [ new LinkHelpTreeItem( "Extension Documentation", @@ -52,6 +67,7 @@ export class HelpTreeDataProvider }, vscode.Uri.parse(buildToolsRepository) ), + walkthroughTreeItem, new LinkHelpTreeItem( "Review Issues", new vscode.ThemeIcon("remote-explorer-review-issues"),