π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
Prune desktop documentation
Manav Rathi041685c5244c
diff --git a/desktop/README.md b/desktop/README.mdindex e6879792d9..623c69ca0e 100644--- a/desktop/README.md+++ b/desktop/README.md@@ -47,15 +47,14 @@ npm run devOr create a binary for your platform```sh+npm run postinstallnpm run build```-That's the gist of it. For more development related documentation, see [docs](docs/README.md).-> [!NOTE]>-> If the relevant `package-lock.json` has not changed since your last `npm ci`, you can use `npm install` as a faster incremental alternative. For caveats, see [docs/dev.md](docs/dev.md#npm-ci-npm-install).+> `npm run dev` will automatically do a `npm run postinstall` if needed. `npm run build` however requires an explicit `npm run postinstall` prior to it.> [!NOTE]>-> `npm run dev` will automatically do a `npm run postinstall` if needed. `npm run build` however requires an explicit `npm run postinstall` prior to it.+> If the relevant `package-lock.json` has not changed since your last `npm ci`, you can use `npm install` as a faster incremental alternative.diff --git a/desktop/docs/README.md b/desktop/docs/README.mddeleted file mode 100644index 3a277ce2ff..0000000000--- a/desktop/docs/README.md+++ /dev/null@@ -1,11 +0,0 @@-# Developer docs--If you just want to run the Ente Photos desktop app locally or develop it, from the repository root you can do:--```sh-cd web && npm ci && cd ..-cd desktop && npm ci && npm run postinstall-npm run dev-```--The docs in this directory provide more details that some developers might find useful. You might also find the developer docs for [web](../../web/docs/README.md) useful.diff --git a/desktop/docs/dependencies.md b/desktop/docs/dependencies.mddeleted file mode 100644index a3a4af7d36..0000000000--- a/desktop/docs/dependencies.md+++ /dev/null@@ -1,89 +0,0 @@-# Dependencies--- [Electron](#electron)-- [Dev dependencies](#dev)-- [Functionality](#functionality)--## Electron--[Electron](https://www.electronjs.org) is a cross-platform (Linux, Windows, macOS) way for creating desktop apps using TypeScript.--Electron embeds Chromium and Node.js in the generated app's binary. The generated app thus consists of two separate processes - the _main_ process, and a _renderer_ process.--- The _main_ process runs the embedded node. This process can deal with the host OS - it is conceptually like a `node` repl running on your machine. In our case, the TypeScript code (in the `src/` directory) gets transpiled by `tsc` into JavaScript in the `build/app/` directory, which gets bundled in the generated app's binary and is loaded by the node (main) process when the app starts.--- The _renderer_ process is a regular web app that gets loaded into the embedded Chromium. When the main process starts, it creates a new "window" that shows this embedded Chromium. In our case, we build and bundle a static export of the [Photos web app](../../web/README.md) in the generated desktop app. This gets loaded by the embedded Chromium at runtime, acting as the desktop app's UI.--There is also a third environment that gets temporarily created:--- The [preload script](../src/preload.ts) acts as a gateway between the _main_ and the _renderer_ process. It runs in its own isolated environment.--### Packaging--[Electron Builder](https://www.electron.build) is used for packaging the app for distribution.--During the build it uses [electron-builder-notarize](https://github.com/karaggeorge/electron-builder-notarize) to notarize the macOS binary.--### Updates--[electron-updater](https://www.electron.build/auto-update#debugging), while a separate package, is also a part of Electron Builder. It provides an alternative to Electron's built in auto updater, with a more flexible API. It supports auto updates for the DMG, AppImage, DEB, RPM and NSIS packages.--[compare-versions](https://github.com/omichelsen/compare-versions) is used for semver comparisons when we decide when to trigger updates.--### Logging--[electron-log](https://github.com/megahertz/electron-log) is used for logging. Specifically, it allows us to log to a file (in addition to the console of the Node.js process), and also handles log rotation and limiting the size of the log files.--### next-electron-server--This spins up a server for serving files using a protocol handler inside our Electron process. This allows us to directly use the output produced by `next build` for loading into our renderer process.--### Others--- [any-shell-escape](https://github.com/boazy/any-shell-escape) is for escaping shell commands before we execute them (e.g. say when invoking the embedded ffmpeg CLI).--- [auto-launch](https://github.com/Teamwork/node-auto-launch) is for automatically starting our app on login, if the user so wishes.--- [electron-store](https://github.com/sindresorhus/electron-store) is used for persisting user preferences and other arbitrary data.--## Dev--See [web/docs/dependencies#dev](../../web/docs/dependencies.md#dev) for the general development experience related dependencies like TypeScript etc, which are similar to that in the web code.--Some extra ones specific to the code here are:--- [@tsconfig/recommended](https://github.com/tsconfig/bases) gives us a base tsconfig for the Node.js version that our current Electron version uses.--- [shx](https://github.com/shelljs/shx) provides us a portable way to use Unix commands in our `package.json` scripts. This allows us to use the same commands (like `ln`) across both POSIX platforms (Linux, macOS) and Windows.--- [cross-env](https://github.com/kentcdodds/cross-env) is similar to shx, but for allowing us to set environment variables in a way that also works on Windows.--- We don't need `ajv`, but it is a transitive dependency which breaks the build if we let its version be resolved transitively. Taking a direct dependency on it is the easiest workaround for now.--## Functionality--### Format conversion--For video conversions and metadata extraction, we use ffmpeg. To bundle a (platform specific) static binary of ffmpeg with our app, we use [ffmpeg-static](https://github.com/eugeneware/ffmpeg-static).--> There is a significant (~20x) speed difference between using the compiled FFmpeg binary and using the Wasm one (that our renderer process already has). Which is why we bundle it to speed up operations on the desktop app.--On Linux and Windows, we use `vips` for thumbnail generation and JPEG conversion of unpreviewable images. A static OS/architecture specific binary of this is bundled in our extra resources (`build`) folder by `scripts/vips.sh` and/or `scripts/beforeBuild.js`. See "[Note: vips]" for more details.--On macOS, we use the `sips` CLI tool for these tasks, but that is already available on the host machine, and is not bundled with our app.--### ML--The ML pipeline (natural language search using CLIP, and face detection and recognition) is implemented by the Rust crate shared with the mobile apps (`rust/crates/photos`), exposed to us as a Node native addon built from source by `scripts/napi.js` (see "[Note: ML with Rust]"). `cargo codegen napi` generates only the TypeScript declarations for that addon.--The addon loads [ONNX Runtime](https://onnxruntime.ai) dynamically at runtime, using Ente's pinned custom builds (CoreML-enabled on macOS) that `scripts/ort.js` installs during postinstall. Development loads the libraries directly from the install cache; packaging stages them into the extra resources (`build`) folder. See "[Note: ONNX Runtime binaries]".--### ZIP--[node-stream-zip](https://github.com/antelle/node-stream-zip) is used for reading of large ZIP files (e.g. during imports of Google Takeout ZIPs).--[lru-cache](https://github.com/isaacs/node-lru-cache) is used to cache file ZIP handles to avoid reopening them for every operation.--### Watch folders--[chokidar](https://github.com/paulmillr/chokidar) is used as a file system watcher for the watch folders functionality.diff --git a/desktop/docs/dev.md b/desktop/docs/dev.mddeleted file mode 100644index 59176ebaae..0000000000--- a/desktop/docs/dev.md+++ /dev/null@@ -1,60 +0,0 @@-# Development--## npm commands--### npm ci, npm install--Use `npm ci` to install dependencies using the committed lockfile. You need this for initial setup, and whenever `package-lock.json` changes (e.g. after pulling the latest upstream).--`npm ci` is the safe default. However, it deletes and recreates `node_modules` each time. For a faster incremental install, you can use `npm install` if you have already run `npm ci` and `package-lock.json` has not changed since then.--> We pin exact versions in `package.json` and commit the lockfile so both `npm install` and `npm ci` should give the same outcome; however, this is not guaranteed, so if `npm install` changes `package-lock.json`, review the diff instead of treating it as incidental churn.--Use `npm install <package>` only when intentionally adding or updating dependencies, and review the resulting `package.json` and `package-lock.json` changes.--The desktop app embeds the Photos web app, so local development also requires installing dependencies in `../web`. The ML pipeline is implemented by the Rust crate shared with the mobile apps and built from source (see [Note: ML with Rust]), so a [Rust toolchain](https://rustup.rs) is also required.--```sh-cd ../web-npm ci-cd ../desktop-npm ci-npm run postinstall-```--### npm run dev--Launch the app in development mode:--- Runs the postinstall script if needed.-- Transpiles the files in `src/` and starts the main process.--- Runs a development server for the renderer, with hot module reload.--The renderer scripts check that `../web` dependencies have been installed. If they are missing or stale, update them before debugging renderer errors: use `npm install` in `../web` if its `package-lock.json` has not changed since your last `npm ci`, otherwise use `npm ci`.--### npm run build--Build a binary for your current platform.--Note that our actual releases use a [GitHub workflow](../../.github/workflows/photos-desktop-build.yml) that is similar to this, except it builds binaries for all the supported OSes and uses production signing credentials.--During development, you might find `npm run build:quick` helpful. It is a variant of `npm run build` that omits some steps to build a binary quicker, something that can be useful during development.--### npm run postinstall--Installs skip dependency lifecycle scripts (`ignore-scripts` in `.npmrc`) so that installing cannot run arbitrary code from packages. The flip side is that our own postinstall does not run automatically either, so it must be invoked explicitly. `npm run dev` runs it automatically if it hasn't run for the currently installed dependencies; for other flows (e.g. `npm run build`) run it yourself after `npm ci`. It:--- Runs the install scripts of the dependencies that fetch prebuilt binaries (`ffmpeg-static`, `electron-winstaller`).--- Runs [electron-builder](https://www.electron.build/cli)'s `install-app-deps` command to rebuild native node modules (those written in C/C++) against `electron`'s packaged `node` version.--- Downloads the `vips` binary used during development (see `scripts/vips.js`).--- Downloads the ONNX Runtime libraries used by the ML pipeline (see `scripts/ort.js`).--Postinstall does not compile the Rust ML addon. `npm run dev` builds an optimized host addon through `scripts/napi.js`; packaging builds optimized target addons through electron-builder's `beforeBuild` hook. `cargo codegen napi` only regenerates the TypeScript declarations in the gitignored `rust-bindings/` directory.--### lint, lint:fix--Use `npm run lint` to check that your code formatting is as expected, and that there are no linter errors. Use `npm run lint:fix` to try and automatically fix the issues.