From 1532ae8836b962b286c3b47e25ce32593ea09df4 Mon Sep 17 00:00:00 2001 From: confused-Techie Date: Mon, 3 Jul 2023 14:48:58 -0700 Subject: [PATCH 1/2] New docs, and slight edits --- docs/README.md | 16 +- .../assets/how-everything-connects.svg | 1 + docs/architecture/assets/pulsar-overview.svg | 11 ++ docs/architecture/overview.md | 178 ++++++++++++++++++ docs/architecture/the-world.md | 101 ++++++++++ 5 files changed, 302 insertions(+), 5 deletions(-) create mode 100644 docs/architecture/assets/how-everything-connects.svg create mode 100644 docs/architecture/assets/pulsar-overview.svg create mode 100644 docs/architecture/overview.md create mode 100644 docs/architecture/the-world.md diff --git a/docs/README.md b/docs/README.md index 094bc6e5b..ab4ad74fc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,22 @@ -# Atom Docs +# Pulsar Docs ![Atom](https://cloud.githubusercontent.com/assets/72919/2874231/3af1db48-d3dd-11e3-98dc-6066f8bc766f.png) -Most of the Atom user and developer documentation is contained in the [Atom Flight Manual](https://github.com/atom/flight-manual.atom.io). +Most of the Pulsar/Atom user and developer documentation is contained on the [Pulsar Website](https://pulsar-edit.dev/docs/launch-manual/). + +While the Pulsar website does not yet have the Pulsar API documentation, this is partially available within [Pulsar API Documentation](./Pulsar-API-Documentation.md) or otherwise the original docs are available from community members [here](https://atom-flight-manual-archive.github.io/). + +## General Documentation + +Resources about the structure of Pulsar available: + * [Overview](./architecture/overview.md) + * ['The World'](./architecture/the-world.md) ## Build documentation Instructions for building Atom on various platforms from source. -* Moved to [the Flight Manual](https://flight-manual.atom.io/hacking-atom/sections/hacking-on-atom-core/) +* Moved to [the Flight Manual](https://pulsar-edit.dev/docs/launch-manual/sections/core-hacking/) * Linux * macOS * Windows @@ -16,5 +24,3 @@ Instructions for building Atom on various platforms from source. ## Other documentation [Native Profiling on macOS](./native-profiling.md) - -The other documentation that was listed here previously has been moved to [the Flight Manual](https://flight-manual.atom.io). diff --git a/docs/architecture/assets/how-everything-connects.svg b/docs/architecture/assets/how-everything-connects.svg new file mode 100644 index 000000000..53a62b707 --- /dev/null +++ b/docs/architecture/assets/how-everything-connects.svg @@ -0,0 +1 @@ +StartupMain Process TestsApplication StartupTest RunnerInitialize Application Window'The World'ConfigScopeDescriptorCommandRegistryURIHandlerRegistryMenuManagerMenuHelpersTextEditorRegistryTextEditorScopeDescriptorDeserializerManagerViewRegistryPackageManagerPackageThemePackageModuleCacheCommandInstallerProtocolHandlerInstallerAutoUpdateManagerWindowEventHandlerlistenGrammarRegistryNodeTreeSitterLanguageModeTextMateLanguageModeScopeDescriptorTokenTreeIndenterTokenizedLinematcherForSelectorScopeDescriptorWASMTreeSitterLanguageNodeParserTextMateLanguageModeTokenIteratorNullGrammarTokenizedLineScopeDescriptorTokenKemapManagerTolltipManagerTooltipStyleManagercreateStylesElementDEPRECATED_SYNTAX_SELECTORSContextMenuManagerMenuHelperssortMenuItemsHistoryManagerNotificationManagerNotificationStateStoreThemeManagerLessCompileCacheProjectwatchPathDefaultDirectoryProviderModelGitRepositoryProviderWorkspaceRipgrepDirectorySearchercreateWorkspaceElementStateStorePanelDockDefaultDirectorySearcherWorkspaceCenterPanelContainerTextEditorTaskStartup w/ SquirrelInitialization \ No newline at end of file diff --git a/docs/architecture/assets/pulsar-overview.svg b/docs/architecture/assets/pulsar-overview.svg new file mode 100644 index 000000000..cb72d3371 --- /dev/null +++ b/docs/architecture/assets/pulsar-overview.svg @@ -0,0 +1,11 @@ +
+

Initialization
./src/main-process/main.js

+

Startup
./src/main-process/start.js

+

Main Process Tests

+

Application Startup
./src/main-process/atom-application.js

+

Startup w/ Squirrel
./src/main-process/squirrel-update.js

+

Test Runner
./src/initialize-test-window.js

+

Initialize Application Window
./src/initialize-application-window.js

+

'The World'
./src/atom-environment.js

+

ApplicationDelegate
./src/application-delegate.js

+

Clipboard
./src/clipboard.js

 \ No newline at end of file diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 000000000..178d804e2 --- /dev/null +++ b/docs/architecture/overview.md @@ -0,0 +1,178 @@ +``` + _____ _ + | __ \ | | + | |__) | _| |___ __ _ _ __ + | ___/ | | | / __|/ _` | '__| + | | | |_| | \__ \ (_| | | + |_| \__,_|_|___/\__,_|_| +``` + +# Pulsar's High Level Overview + +It's no secret that Pulsar since inherited from Atom, is a big and complex application. + +With many discrete, moving aspects, that not all developers have a concrete grasp on. +The goal of this document is to make the architecture of Pulsar, as well as the logical flow +more understandable and approachable. + +This will be accomplished through a series of illustrations detailing the functional decomposition and detailed logical flow of Pulsar and it's parts, as well as lists of what's accomplished in each part. + +This document is aimed at those roughly familiar with the large scale goals and features of Pulsar, as well as those with a basic understanding of the package model used to power much of Pulsar's functionality. + +![Pulsar Overview MermaidJS Image](./assets/pulsar-overview.svg "Pulsar Overview") + +
+ +MermaidJS to create image above + + +``` +flowchart TD + id1("`Initialization + *./src/main-process/main.js*`") --> id2("`Startup + *./src/main-process/start.js*`") + id2 --> id3("`Main Process Tests`") + id2 --> id4("`Application Startup + *./src/main-process/atom-application.js*`") + id2 --> id5("`Startup w/ Squirrel + *./src/main-process/squirrel-update.js*`") + id4 --> id6("`Test Runner + *./src/initialize-test-window.js*`") + id4 --> id7("`Initialize Application Window + *./src/initialize-application-window.js*`") + id7 --> id9("`'The World' + *./src/atom-environment.js*`") + id7 --> id10("`ApplicationDelegate + *./src/application-delegate.js*`") + id7 --> id8("`Clipboard + *./src/clipboard.js*`") + id8 --> id9 + id10 --> id9 +``` + +
+ +--- + +To further outline what occurs in the steps above: + +## Initialization + +Startup of Pulsar occurs within `./src/main-process/main.js`. + +Which Determines: + - `resourcePath` + - `devResourcePath` + - `stableResourcePath` + - `defaultRepositoryPath` + +Which Sets: + - Application Start Time + +Which Does: + - Initializes Startup of `./src/main-process/start.js` + +## Startup + +The more general startup handling of Pulsar occurs within `./src/main-process/start.js`. + +Which Sets: + - Shell Start Time + - `app.allowRendererProcessReuse`: `false` + - `app.commandLine.appendSwitch('enable-experimental-web-platform-features')` + - `app.commandLine.appendSwitch('force-color-profile', config.get('core.colorProfile'))` + - `app.setAppUserModelId()` + - `app.on('open-file', $)` + - `app.on('open-url', $)` + +Which Does: + - Normalizes the `resourcePath` and `devResourcePath` + - Uses `Config` to locate and read the config file + - `atomPaths.setAtomHome()` + - `atomPaths.setUserData()` + - May defer to `./src/main-process/squirrel-update.js` to startup if on Windows + - May defer to `./spec/main-process/mocha-test-runner.js` to startup main process tests + - May call `.open()` on `./src/main-process/atom-application.js` + +## Application Startup + +The proper startup of the Pulsar Application occurs within `./src/main-process/atom-application.js`. + +Which Sets: + - `APPLICATION_STATE_VERSION` + - Global `atomApplication` + +Which Does: + - Does setup of the application socket + - Handles deprecated benchmark startup + - Ensures to return a new instance of `AtomApplication` + - Registers basic application commands + - Initializes: + * `ApplicationMenu` + * `AtomProtocolHandler` + * `WindowStack` + * `FileRecoveryService` + * `Config` + * `StorageFolder` + * `AutoUpdateManager` + - May startup the package test runner + - May quit if asked to startup in benchmark mode + - May open previously opened files/folders + - May open new instance of Pulsar + +## Initialize Application Window + +Begins initialization of an individual Pulsar window, occurs within `./src/initialize-application-window.js`. + +Which Determines: + +Which Sets: + - Sets the `global.atom` to a new instance of `AtomEnvironment` + +Which Does: + - triggers `.preloadPackages()` + - Initializes: + * Clipboard + * AtomEnvironment + * ApplicationDelegate + +## 'The World' + +'The World' refers to being within the Pulsar application, most of the application occurs within here. +This code lives within `./src/atom-environment.js`. + +An important note about being initialized within the world, there is no access to the `atom` +global, until the initial constructor completes processing. Meaning great care must be taken +to ensure if `atom` is available within the initialized modules. + +Which Sets: + - `AtomEnvironment.version`: `1` | Possibly a reference to `APPLICATION_STATE_VERSION`? + - `AtomEnvironment.saveStateDebounceInterval`: `1000` + +Which Does: + - Initializes: + * Clipboard | Inherited from 'Initialize Application Window' + * ApplicationDelegate | Inherited from 'Initialize Application Window' + * DeserializerManager + * ViewRegistry + * NotificationManager + * StateStore + * Config + * KeymapManager + * TooltipManager + * CommandRegistry + * URIHandlerRegistry + * GrammarRegistry + * StyleManager + * PackageManager + * ThemeManager + * MenuManager + * ContextMenuManager + * Project + * CommandInstaller + * ProtocolHandlerInstaller + * TextEditorRegistry + * Workspace + * AutoUpdateManager + * WindowEventHandler + * HistoryManager diff --git a/docs/architecture/the-world.md b/docs/architecture/the-world.md new file mode 100644 index 000000000..a2814c209 --- /dev/null +++ b/docs/architecture/the-world.md @@ -0,0 +1,101 @@ +# 'The World' + +While it's difficult to convey the full scope of how Pulsar works internally, just like the previous page [`overview.md`](./overview.md) detailed the general gist of how Pulsar starts up, this document provides a quick reference to how all the interal parts of Pulsar are connected. + +This document is not at all comprehensive, and must ensure to be continually updated. Additionally, this image does not track outside dependency usage, nor dependence on every single internal module. Focusing mostly on modules that are either required during initialization, or are referenced during the constructor of their respective class. + +
+ +Details on the creation of this image + + +This image has been created with Plant UML. A Live editor is available [here](https://www.plantuml.com/plantuml/uml). + +The code used to create this image: + +```uml +@startwbs +* Initialization +** Startup +***< Main Process Tests +*** Startup w/ Squirrel +***< Application Startup +****< Test Runner +**** Initialize Application Window +***** 'The World' +******< Config +******* ScopeDescriptor +****** KemapManager +****** TolltipManager +******* Tooltip +******< CommandRegistry +******< URIHandlerRegistry +****** StyleManager +******* createStylesElement +******* DEPRECATED_SYNTAX_SELECTORS +******< MenuManager +******* MenuHelpers +****** ContextMenuManager +******* MenuHelpers +******* sortMenuItems +******< TextEditorRegistry +******* TextEditor +******* ScopeDescriptor +****** HistoryManager +******< DeserializerManager +******< ViewRegistry +****** NotificationManager +******* Notification +****** StateStore +******< PackageManager +******* Package +******* ThemePackage +******* ModuleCache +****** ThemeManager +******* LessCompileCache +****** Project +******* watchPath +******* DefaultDirectoryProvider +******* Model +******* GitRepositoryProvider +******< CommandInstaller +******< ProtocolHandlerInstaller +******< AutoUpdateManager +******< WindowEventHandler +******* listen +******< GrammarRegistry +*******< NodeTreeSitterLanguageMode +******** TreeIndenter +********< TextMateLanguageMode +******** TokenizedLine +********< ScopeDescriptor +******** matcherForSelector +********< Token +******* WASMTreeSitterLanguageNode +******** Parser +******* TextMateLanguageMode +******** TokenizedLine +********< TokenIterator +******** ScopeDescriptor +********< NullGrammar +*******< ScopeDescriptor +******* Token +****** Workspace +******* DefaultDirectorySearcher +*******< RipgrepDirectorySearcher +******* WorkspaceCenter +*******< createWorkspaceElement +******* PanelContainer +*******< StateStore +******* TextEditor +*******< Panel +******* Task +*******< Dock +@endwbs +``` + +
+ +--- + +![Pulsar 'How Everything Connects' UML Image](./assets/how-everything-connects.svg "Pulsar 'How Everything Connects'") From 12a0b82f06772b4ca0c323c17777584374aec331 Mon Sep 17 00:00:00 2001 From: confused-Techie Date: Mon, 3 Jul 2023 17:48:50 -0700 Subject: [PATCH 2/2] Update docs, and add `package-preload` docs --- docs/README.md | 6 +- docs/architecture/README.md | 10 +++ docs/architecture/assets/package-preload.svg | 6 ++ docs/architecture/overview.md | 11 +--- docs/architecture/package-preload.md | 66 ++++++++++++++++++++ 5 files changed, 84 insertions(+), 15 deletions(-) create mode 100644 docs/architecture/README.md create mode 100644 docs/architecture/assets/package-preload.svg create mode 100644 docs/architecture/package-preload.md diff --git a/docs/README.md b/docs/README.md index ab4ad74fc..43a8dc750 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,11 +6,7 @@ Most of the Pulsar/Atom user and developer documentation is contained on the [Pu While the Pulsar website does not yet have the Pulsar API documentation, this is partially available within [Pulsar API Documentation](./Pulsar-API-Documentation.md) or otherwise the original docs are available from community members [here](https://atom-flight-manual-archive.github.io/). -## General Documentation - -Resources about the structure of Pulsar available: - * [Overview](./architecture/overview.md) - * ['The World'](./architecture/the-world.md) +There is also general guidance on the internal [stucture and behavior](./architecture/README.md) of Pulsar available. ## Build documentation diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 000000000..76223562f --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,10 @@ +# Pulsar Architecture + +This directory contains a collection of files and diagrams, that aim to easily explain some of the core components or behaviors of Pulsar. + +Remember that keeping this charts up to date is best effort, and the age of these files should be taken into consideration. + +## Contents + - [Startup Overview](./overview.md) + - ['The World'](./the-world.md) + - [Package Preload](./package-preload.md) diff --git a/docs/architecture/assets/package-preload.svg b/docs/architecture/assets/package-preload.svg new file mode 100644 index 000000000..3ea2a1d9a --- /dev/null +++ b/docs/architecture/assets/package-preload.svg @@ -0,0 +1,6 @@ +
if in packageCache
sg1
call .preload()
call .preload()
preloadPackage()
new ThemePackage
new Package
+

this.preload() call:
Does more than advertised here

.loadKeymaps()
+

Read from packagesCache:
If bundled package && in packagesCache

+

Read from file:
If !bundled || !in packagesCache

.loadMenus()
.activateCoreStartupServices()
.requireMainModule()
.loadSettings()
.activateKeymaps()
.activateMenus()
.preload()
.reigsterConfigSchemaFromMetadata()
+

initialize-application-window.js
Called right after global 'atom' is set

+

AtomEnvironment
.preloadPackages()

preloadPackages()
 \ No newline at end of file diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 178d804e2..765aedf5b 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,13 +1,4 @@ -``` - _____ _ - | __ \ | | - | |__) | _| |___ __ _ _ __ - | ___/ | | | / __|/ _` | '__| - | | | |_| | \__ \ (_| | | - |_| \__,_|_|___/\__,_|_| -``` - -# Pulsar's High Level Overview +# Pulsar's High Level Startup Overview It's no secret that Pulsar since inherited from Atom, is a big and complex application. diff --git a/docs/architecture/package-preload.md b/docs/architecture/package-preload.md new file mode 100644 index 000000000..da20bf3aa --- /dev/null +++ b/docs/architecture/package-preload.md @@ -0,0 +1,66 @@ +# Package Preload + +Pulsar's packages are preloaded, very early on within the startup cycle of Pulsar. + +As it's called immediatly after the `atom` global is initialized, it's important to understand what steps occur during preloading, and what package's are affected. + +![Package Preload Overview](./assets/package-preload.svg "Package Preload Overview") + +--- + +
+ +MermaidJS to create image above + + +``` +flowchart TD + iaw["` + initialize-application-window.js + Called right after global 'atom' is set + `"] --> + ae["` + AtomEnvironment + .preloadPackages() + `"] --> + pl1["preloadPackages()"] -->|if in packageCache| sg1 + + subgraph sg1 + direction LR + pl2["preloadPackage()"] + pl2 -->|"call .preload()"| tp1["new ThemePackage"] + pl2 -->|"call .preload()"| p1["new Package"] + + p1 --> p1Pre["` + this.preload() call: + Does more than advertised here + `"] + + p1Pre --> lk1[".loadKeymaps()"] + lk1 --> pcRead1["`Read from packagesCache: + If bundled package && in packagesCache`"] + lk1 --> fileRead1["`Read from file: + If !bundled || !in packagesCache`"] + + p1Pre --> lm1[".loadMenus()"] + lm1 --> pcRead1 + lm1 --> fileRead1 + + p1Pre --> acss[".activateCoreStartupServices()"] + p1Pre --> rmm[".requireMainModule()"] + + acss --> rmm + + p1Pre --> ls1[".loadSettings()"] + ls1 --> pcRead1 + ls1 --> fileRead1 + + p1Pre --> ak1[".activateKeymaps()"] + p1Pre --> am1[".activateMenus()"] + + tp1 --> tp1Pre[".preload()"] + tp1Pre --> csrol1[".reigsterConfigSchemaFromMetadata()"] + end +``` + +