diff --git a/.github/workflows/archaeologist-dig.yml b/.github/workflows/archaeologist-dig.yml index d284e8b98bc1a..d921e9f24bbc0 100644 --- a/.github/workflows/archaeologist-dig.yml +++ b/.github/workflows/archaeologist-dig.yml @@ -23,6 +23,7 @@ jobs: - name: Setting Up Dig Site env: CLONE_URL: ${{ github.event.pull_request.head.repo.clone_url }} + BASE_CLONE_URL: ${{ github.event.pull_request.base.repo.clone_url }} HEAD_SHA: ${{ github.event.pull_request.head.sha }} BASE_REF: ${{ github.event.pull_request.base.ref }} run: | @@ -33,8 +34,9 @@ jobs: cd electron mkdir -p artifacts git remote add fork "$CLONE_URL" && git fetch fork + git remote add base "$BASE_CLONE_URL" && git fetch base git checkout "$HEAD_SHA" - git merge-base "origin/$BASE_REF" HEAD > .dig-old + git merge-base "base/$BASE_REF" HEAD > .dig-old echo "$HEAD_SHA" > .dig-new cp .dig-old artifacts diff --git a/.github/workflows/bs_electron_build_and_test.yml b/.github/workflows/bs_electron_build_and_test.yml new file mode 100644 index 0000000000000..9673976a863f1 --- /dev/null +++ b/.github/workflows/bs_electron_build_and_test.yml @@ -0,0 +1,299 @@ +name: 'BrightSign Build and Test Electron: Build and test workflow' +on: + workflow_call: + inputs: + runner_name: + required: true + type: string + + github_hosted_runner: + required: true + type: boolean + + build_type: + required: true + type: string + # "test" or "release" + + aws_arn_role: + required: true + type: string + + aws_region: + required: true + type: string + +jobs: + build-and-test-electron: + name: Build and Test Electron + runs-on: ${{ inputs.runner_name }} + defaults: + run: + working-directory: ./ + + steps: + # Cleanups only needed for self hosted runners + # - name: Clean up work dir (temp instead of colpal/actions-clean@v1, until docker usage issue with sock file permissions sorted) + # run: rm -rf * + + # - name: Cleanup work dir + # uses: colpal/actions-clean@v1 + # if: ${{ always() }} # To ensure this step runs even when earlier steps fail + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1-node16 + with: + aws-region: ${{ inputs.aws_region}} + role-to-assume: ${{ inputs.aws_arn_role }} + # Set role-duration-seconds to 10 hours + role-duration-seconds: 36000 + + - name: Setup Node + uses: actions/setup-node@v3 + with: + node-version: 24 + + - name: Download config file and set env vars from it + run: | + aws s3 cp s3://electron-ci-config-bucket/config.json . + aws s3 cp s3://electron-ci-config-bucket/set_github_env_vars.py . + python3 set_github_env_vars.py --file config.json + + - name: Check build type + if: inputs.build_type != 'test' && inputs.build_type != 'release' + run: | + echo "ERROR> build_type is set to \"${{ inputs.build_type }}\" and should be set to \"test\" or \"release\"" + exit 1 + + - name: Install dependencies if Github hosted runner + if: inputs.github_hosted_runner == true + run: | + # From https://www.electronjs.org/docs/latest/development/build-instructions-linux + sudo apt-get update + sudo apt-get install -y build-essential clang libdbus-1-dev libgtk-3-dev \ + libnotify-dev libasound2-dev libcap-dev \ + libcups2-dev libxtst-dev \ + libxss1 libnss3-dev gcc-multilib g++-multilib curl \ + gperf bison python3-dbusmock openjdk-8-jre + + # virtual framebuffer for running tests. + sudo apt install -y xvfb + + # A fix for test case (to remove fonts-liberation that seems to be installed by default in Github default ubuntu image)... + # 2022-12-23T10:56:48.4520914Z not ok 2079 font fallback should use Helvetica for sans-serif on Mac, and Arial on Windows and Linux + # 2022-12-23T10:56:48.4522432Z AssertionError: expected 'Liberation Sans' to equal 'DejaVu Sans' + # 2022-12-23T10:56:48.4523556Z at Context. (electron/spec/chromium-spec.ts:2222:38) + sudo apt-get remove -y fonts-liberation + + - name: Install and setup sccache + run: | + # export SCCACHE_ERROR_LOG="$PWD"/sccache.log + # export SCCACHE_LOG="info,sccache::cache=debug" + + curl -o sccache_package.tar.gz -L https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz + echo "1fbb35e135660d04a2d5e42b59c7874d39b3deb17de56330b25b713ec59f849b sccache_package.tar.gz" | shasum -a 256 -c + + tar xzf sccache_package.tar.gz --strip-components=1 + sudo ln -s "$PWD"/sccache /usr/local/bin/sccache + + # echo '/home/ubuntu/.cargo/bin/sccache' >> $GITHUB_PATH + echo 'SCCACHE_REGION=${{ inputs.aws_region }}' >> $GITHUB_ENV + echo 'SCCACHE_CACHE_SIZE=100G' >> $GITHUB_ENV + + - name: Checkout + uses: actions/checkout@v3 + with: + path: ./src/electron + fetch-depth: 0 + + - name: Get electron_version + run: echo "ELECTRON_VERSION=v$(python3 ./src/electron/script/get-git-version.py)" >> $GITHUB_ENV + + - name: Setup build type Testing + if: inputs.build_type == 'test' + run: | + echo "Setting up build type as testing" + echo 'OUTPUT_FOLDER=out/Testing' >> $GITHUB_ENV + echo 'GN_IMPORT=//electron/build/args/testing.gn' >> $GITHUB_ENV + echo 'SCCACHE_BUCKET=${{ env.SCCACHE_TEST_BUILD_BUCKET_NAME }}' >> $GITHUB_ENV + + - name: Setup build type Release + if: inputs.build_type == 'release' + run: | + echo "Setting up build type as release" + echo 'OUTPUT_FOLDER=out/Release' >> $GITHUB_ENV + echo 'GN_IMPORT=//electron/build/args/release.gn' >> $GITHUB_ENV + echo 'SOURCE_RELEASE_FILE_NAME=${{ env.ELECTRON_VERSION }}' >> $GITHUB_ENV + echo 'RELEASE_SRC_FOLDER=${{ env.ELECTRON_VERSION }}' >> $GITHUB_ENV + echo 'RELEASE_DST_FOLDER=${{ env.ELECTRON_VERSION }}' >> $GITHUB_ENV + echo 'SCCACHE_BUCKET=${{ env.SCCACHE_RELEASE_BUILD_BUCKET_NAME }}' >> $GITHUB_ENV + + - name: Display sccache config + run: | + # echo $SCCACHE_BUCKET $SCCACHE_REGION $SCCACHE_CACHE_SIZE + + sccache -s + + - name: Configure Git cache params + run: | + echo 'GIT_CACHE_FOLDER_NAME=git-cache' >> $GITHUB_ENV + echo 'GIT_CACHE_PATH='"$PWD"'/git-cache' >> $GITHUB_ENV + echo 'GIT_CACHE_FILENAME=git-cache-${{ hashFiles('src/electron/DEPS') }}.tar.gz' >> $GITHUB_ENV + + - name: Get depot tools + run: git clone --depth=1 https://chromium.googlesource.com/chromium/tools/depot_tools.git + + - name: Add depot tools to PATH + run: echo ''"$PWD"'/depot_tools' >> $GITHUB_PATH + + - name: Retrieve git-cache + run: | + aws s3api head-object --bucket ${{ env.GIT_CACHE_BUCKET_NAME }} --key $GIT_CACHE_FILENAME || not_exist=true + if [ $not_exist ]; then + echo "Git cache ${GIT_CACHE_FILENAME} not found in bucket ${{ env.GIT_CACHE_BUCKET_NAME }}" + echo "GIT_CACHE_RESTORED=false" >> $GITHUB_ENV + else + echo "Git cache ${GIT_CACHE_FILENAME} found in bucket ${{ env.GIT_CACHE_BUCKET_NAME }}" + echo "GIT_CACHE_RESTORED=true" >> $GITHUB_ENV + aws s3 cp s3://${{ env.GIT_CACHE_BUCKET_NAME }}/$GIT_CACHE_FILENAME $GIT_CACHE_FILENAME --quiet + echo "Downloaded ${GIT_CACHE_FILENAME}" + tar --use-compress-program=pigz -xf $GIT_CACHE_FILENAME + echo "Uncompressed ${GIT_CACHE_FILENAME}" + rm $GIT_CACHE_FILENAME + fi + + - name: GClient sync + run: | + gclient config --name "src/electron" --unmanaged git@github.com:${{ github.repository }}.git + gclient sync --with_branch_heads --with_tags + + # TEMP if you don't do gsync + # cd src/electron + # gclient sync -f + + - name: Save git-cache cache if needed + if: env.GIT_CACHE_RESTORED == 'false' + run: | + tar --use-compress-program=pigz -cf $GIT_CACHE_FILENAME ./$GIT_CACHE_FOLDER_NAME + aws s3 cp $GIT_CACHE_FILENAME s3://${{ env.GIT_CACHE_BUCKET_NAME }}/$GIT_CACHE_FILENAME --storage-class ONEZONE_IA --quiet + + - name: Create source tarball and copy to artifacts bucket + if: inputs.build_type == 'release' + run: | + mkdir -p ${{ env.RELEASE_SRC_FOLDER }} + + echo "Fetching chromium build tools to get export_tarball.py" + git clone https://chromium.googlesource.com/chromium/tools/build --depth 1 + + echo "Running export_tarball.py" + ./build/recipes/recipe_modules/chromium/resources/export_tarball.py $RELEASE_SRC_FOLDER/${{ env.SOURCE_RELEASE_FILE_NAME }} --basename src --src-dir=./src --version=${{ env.ELECTRON_VERSION }} --remove-nonessential-files + + echo "Uploading source tarball" + aws s3 cp ${{ env.RELEASE_SRC_FOLDER }}/${{ env.SOURCE_RELEASE_FILE_NAME }}.tar.xz s3://${{ env.ARTIFACT_BUCKET_NAME }}/${{ env.RELEASE_DST_FOLDER }}/ --acl public-read --quiet + + - name: Set CHROMIUM_BUILDTOOLS_PATH env var + run: echo 'CHROMIUM_BUILDTOOLS_PATH='"$PWD"'/src/buildtools' >> $GITHUB_ENV + + - name: Make sure electron git pack-refs file is present + # This is to stop ninja getting into an infinte loop of "[0/1] Regenerating ninja files" + # Found this file was the issue (as it was missing for some reason) by manually running ninja with -d explain + run: | + cd src/electron + git pack-refs --all + + - name: Run GN Gen + run: | + cd src + gn gen $OUTPUT_FOLDER --args="import(\"${GN_IMPORT}\") cc_wrapper=\"sccache\"" + + - name: Run Ninja Build + run: | + cd src + ninja -C $OUTPUT_FOLDER electron + + - name: Build other items for tests + if: inputs.build_type == 'test' + run: | + cd src + ninja -C $OUTPUT_FOLDER electron:node_headers + + - name: Display sccache stats + run: sccache -s + + - name: Check disk space + run: df -h + + - name: Run unit tests + if: inputs.build_type == 'test' + run: | + cd src/electron + xvfb-run node script/spec-runner --disable-gpu + + - name: Run Node.js Smoke Tests + if: inputs.build_type == 'test' + run: | + cd src/electron + xvfb-run node script/node-spec-runner.js --default + + - name: Prepare release dist and upload + if: inputs.build_type == 'release' + run: | + cd src + ninja -C $OUTPUT_FOLDER electron:electron_dist_zip electron:node_headers electron:hunspell_dictionaries_zip + if [ "`uname`" == "Darwin" ]; then + target_os=mac + target_cpu=x64 + if [ x"$MAS_BUILD" == x"true" ]; then + target_os=mac_mas + fi + if [ "$TARGET_ARCH" == "arm64" ]; then + target_cpu=arm64 + fi + elif [ "`uname`" == "Linux" ]; then + target_os=linux + if [ x"$TARGET_ARCH" == x ]; then + target_cpu=x64 + else + target_cpu="$TARGET_ARCH" + fi + else + echo "Unknown system: `uname`" + exit 1 + fi + echo "Checking dist_zip.${target_os}.${target_cpu}.manifest" + echo "TARGET_OS_CPU=${target_os}-${target_cpu}" >> $GITHUB_ENV + electron/script/zip_manifests/check-zip-manifest.py $OUTPUT_FOLDER/dist.zip electron/script/zip_manifests/dist_zip.$target_os.$target_cpu.manifest + + - name: Prepare release package and upload to artifacts bucket + if: inputs.build_type == 'release' + run: | + cd ${{ env.RELEASE_SRC_FOLDER }} + mkdir package + cd package + unzip -q ../../src/out/Release/dist.zip -d ./dist + cp ../../src/electron/npm/* . + cp ../../src/electron/electron.d.ts . + cp ../../src/LICENSE . + + # Normally when electron is installed it will run install.js which will download the binary, create path.txt + # and copy fields 'name', 'repository', 'description', 'license', 'author', 'keywords' from the root package.json. + + # We will manually do these steps and clear install.js + + echo -n "electron" > path.txt + echo "" > install.js + + echo "$(jq '. += {"name": "electron"}' package.json)" > package.json + echo "$(jq '. += {"repository": "https://github.com/brightsign/electron"}' package.json)" > package.json + echo "$(jq '. += {"description": "Build cross platform desktop apps with JavaScript, HTML, and CSS"}' package.json)" > package.json + echo "$(jq '. += {"license": "MIT"}' package.json)" > package.json + echo "$(jq '. += {"author": "Electron Community"}' package.json)" > package.json + echo "$(jq '. += {"keywords": [ "electron" ] }' package.json)" > package.json + echo "$(jq '. += {"version": "${{ env.ELECTRON_VERSION }}"}' package.json)" > package.json + + electron_package_name="electron-package-${{ env.TARGET_OS_CPU }}-${{ env.SOURCE_RELEASE_FILE_NAME }}.tar.gz" + echo "Creating $electron_package_name" + tar --use-compress-program=pigz -cf "../$electron_package_name" . + cd .. + + echo "Uploading $electron_package_name to s3://${{ env.ARTIFACT_BUCKET_NAME }}/${{ env.RELEASE_DST_FOLDER }}/" + aws s3 cp $electron_package_name s3://${{ env.ARTIFACT_BUCKET_NAME }}/${{ env.RELEASE_DST_FOLDER }}/ --acl public-read --quiet diff --git a/.github/workflows/bs_electron_ci_ec2.yml b/.github/workflows/bs_electron_ci_ec2.yml new file mode 100644 index 0000000000000..41051e387dc08 --- /dev/null +++ b/.github/workflows/bs_electron_ci_ec2.yml @@ -0,0 +1,108 @@ +name: 'BrightSign Build and Test Electron: EC2 controller' +on: + workflow_call: + inputs: + build_type: + description: 'Build Type' + required: true + type: string + + instance_type: + description: 'EC2 instance type' + required: false + type: string + default: c6a.4xlarge + + leave_ec2_instance_running: + description: 'Leave EC2 instance running after use' + type: boolean + default: false + + instance_name_postfix: + description: 'Name to add as postfix to the EC2 machine' + type: string + default: auto-triggered + + aws_arn_role: + required: true + type: string + + aws_region: + required: true + type: string + +jobs: + start-runner: + name: Start self-hosted EC2 runner + runs-on: ubuntu-latest + outputs: + label: ${{ steps.start-ec2-runner.outputs.label }} + ec2-instance-id: ${{ steps.start-ec2-runner.outputs.ec2-instance-id }} + steps: + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1-node16 + with: + aws-region: ${{ inputs.aws_region }} + role-to-assume: ${{ inputs.aws_arn_role }} + + - name: Download config file and set env vars from it + run: | + aws s3 cp s3://electron-ci-config-bucket/config.json . + aws s3 cp s3://electron-ci-config-bucket/set_github_env_vars.py . + python set_github_env_vars.py --file config.json + + - name: Start EC2 runner + id: start-ec2-runner + uses: brightsign/ec2-github-runner@3ef5e07bd58c60757b26c39b8cf25f234df7b974 + with: + mode: start + github-app-private-key: ${{ secrets.GH_APP_PRIVATE_KEY }} + github-app-id: 287690 + ec2-image-id: ami-0aa7bb41d6a04e736 + ec2-instance-type: ${{ inputs.instance_type }} + subnet-id: ${{ env.VPC_SUBNET_ID }} + security-group-id: ${{ env.VPC_SG_ID }} + run-as-service-with-user: ubuntu + runner-home-dir: /home/ubuntu + # iam-role-name: my-role-name # optional, requires additional permissions + aws-resource-tags: > # optional, requires additional permissions + [ + {"Key": "Name", "Value": "github-runner-${{ inputs.instance_name_postfix }}"}, + {"Key": "GitHubRepository", "Value": "${{ github.repository }}"} + ] + + build-and-test-electron: + name: Build and Test Electron + needs: start-runner # required to start the main job when the runner is ready + uses: ./.github/workflows/bs_electron_build_and_test.yml + secrets: inherit + with: + runner_name: ${{ needs.start-runner.outputs.label }} # run the job on the newly created runner + github_hosted_runner: false + build_type: ${{ inputs.build_type }} + aws_arn_role: ${{ inputs.aws_arn_role }} + aws_region: ${{ inputs.aws_region }} + + stop-runner: + name: Stop self-hosted EC2 runner + needs: + - start-runner # required to get output from the start-runner job + - build-and-test-electron # required to wait when the main job is done + runs-on: ubuntu-latest + if: ${{ always() }} # required to stop the runner even if the error happened in the previous jobs + steps: + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1-node16 + with: + role-to-assume: ${{ inputs.aws_arn_role }} + aws-region: ${{ inputs.aws_region }} + + - name: Stop EC2 runner + uses: brightsign/ec2-github-runner@3ef5e07bd58c60757b26c39b8cf25f234df7b974 + with: + mode: stop + github-app-private-key: ${{ secrets.GH_APP_PRIVATE_KEY }} + github-app-id: 287690 + label: ${{ needs.start-runner.outputs.label }} + ec2-instance-id: ${{ needs.start-runner.outputs.ec2-instance-id }} + leave-ec2-instance-running: ${{ inputs.leave_ec2_instance_running }} diff --git a/.github/workflows/bs_electron_ci_manual_process.yml b/.github/workflows/bs_electron_ci_manual_process.yml new file mode 100644 index 0000000000000..7b5f7ff047d96 --- /dev/null +++ b/.github/workflows/bs_electron_ci_manual_process.yml @@ -0,0 +1,41 @@ +name: 'BrightSign Manual Build Process' +on: + workflow_dispatch: + inputs: + build_type: + description: 'Build Type' + type: choice + options: + - test + - release + + instance_type: + description: 'EC2 Instance Type' + type: choice + options: + - c6a.large + - c6a.xlarge + - c6a.2xlarge + - c6a.4xlarge + - c6a.8xlarge + + leave_ec2_instance_running: + description: 'Leave EC2 instance running after use' + type: boolean + default: false + +permissions: + id-token: write # This is required for requesting the JWT + contents: read # This is required for actions/checkout + +jobs: + call-build-and-test: + uses: ./.github/workflows/bs_electron_ci_ec2.yml + secrets: inherit + with: + build_type: ${{ inputs.build_type }} + instance_type: ${{ inputs.instance_type }} + leave_ec2_instance_running: ${{ inputs.leave_ec2_instance_running }} + instance_name_postfix: manual--${{ github.actor }} + aws_arn_role: arn:aws:iam::195607249165:role/github-actions-electron-repo + aws_region: us-east-1 diff --git a/.github/workflows/bs_electron_ci_release_process.yml b/.github/workflows/bs_electron_ci_release_process.yml new file mode 100644 index 0000000000000..5ad725b0a3093 --- /dev/null +++ b/.github/workflows/bs_electron_ci_release_process.yml @@ -0,0 +1,35 @@ +name: 'BrightSign Release Processes' +on: + create: + delete: + tags: + +permissions: + id-token: write # This is required for requesting the JWT + contents: read # This is required for actions/checkout + +jobs: + create-release: + if: github.event_name == 'create' && github.event.ref_type == 'tag' + uses: ./.github/workflows/bs_electron_ci_ec2.yml + secrets: inherit + with: + build_type: release + aws_arn_role: arn:aws:iam::195607249165:role/github-actions-electron-repo + aws_region: us-east-1 + + delete-release: + if: github.event_name == 'delete' && github.event.ref_type == 'tag' # startsWith(github.ref, 'refs/tags/') + runs-on: ubuntu-latest + steps: + - name: Info + run: echo "TODO.. Delete release with Tag" ${{ github.event.ref }} + + # debug: + # runs-on: ubuntu-latest + # steps: + # - name: Dump GitHub context + # env: + # GITHUB_CONTEXT: ${{ toJson(github) }} + # run: | + # echo "$GITHUB_CONTEXT" diff --git a/.github/workflows/bs_electron_ci_test_process.yml b/.github/workflows/bs_electron_ci_test_process.yml new file mode 100644 index 0000000000000..d324bcf9a0eea --- /dev/null +++ b/.github/workflows/bs_electron_ci_test_process.yml @@ -0,0 +1,27 @@ +name: 'BrightSign Test Process' +on: + pull_request: + # branches: [ "main" ] + +permissions: + id-token: write # This is required for requesting the JWT + contents: read # This is required for actions/checkout + +jobs: + test-pr: + if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'synchronize') + uses: ./.github/workflows/bs_electron_ci_ec2.yml + secrets: inherit + with: + build_type: test + aws_arn_role: arn:aws:iam::195607249165:role/github-actions-electron-repo + aws_region: us-east-1 + + # debug: + # runs-on: ubuntu-latest + # steps: + # - name: Dump GitHub context + # env: + # GITHUB_CONTEXT: ${{ toJson(github) }} + # run: | + # echo "$GITHUB_CONTEXT" diff --git a/docs/api/app.md b/docs/api/app.md index 41e4a5f7f83e3..2591b6f32448d 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -1726,6 +1726,18 @@ app.setClientCertRequestPasswordHandler(async ({ hostname, tokenName, isRetry }) }) ``` +### `app.addFont(path)` _Linux_ + +* `path` string - A path to the ttf font file. + +Returns `boolean` - Whether the font was successfully added. + +This method calls fontconfig's `FcConfigAppFontAddFile` to add a font to the +application's font configuration. This allows the application to use the font +without having to install it system-wide. The font will be available to all +web contents in the application, but will not be available to other applications +or the system. + ## Properties ### `app.accessibilitySupportEnabled` _macOS_ _Windows_ diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 2779ed08fd84a..7aee2e99ce115 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -457,6 +457,15 @@ Calling `event.preventDefault()` will prevent the menu from being displayed. To convert `point` to DIP, use [`screen.screenToDipPoint(point)`](./screen.md#screenscreentodippointpoint-windows-linux). +#### Event: 'virtual-keyboard-visibility-changed' + +Returns: + +* `event` Event +* `show` boolean + +Emitted when Browser requests to show or hide a virtual keyboard + ### Static Methods The `BrowserWindow` class has the following static methods: @@ -1803,6 +1812,16 @@ with `addBrowserView` or `setBrowserView`. The top-most BrowserView is the last > The `BrowserView` class is deprecated, and replaced by the new > [`WebContentsView`](web-contents-view.md) class. +#### `win.setWindowTransform(windowTransform)` _Linux_ + +* `windowTransform` string + * `none` - There is no transform (i.e. the widget content is oriented as landscape). + * `rot90` - The widget content is rotated to portrait at 90 degrees (clockwise). + * `rot180` - The widget content is rotated to portrait at 180 degrees (clockwise). + * `rot270` - The widget content is rotated to portrait at 270 degrees (clockwise). + +This method sets the browser window's transform. + #### `win.setTitleBarOverlay(options)` _Windows_ _Linux_ * `options` Object diff --git a/docs/api/memory-pressure-monitor.md b/docs/api/memory-pressure-monitor.md new file mode 100644 index 0000000000000..a0ffb7dc6bc20 --- /dev/null +++ b/docs/api/memory-pressure-monitor.md @@ -0,0 +1,80 @@ +# memoryPressureMonitor + +> Monitor and trigger system memory pressure events. + +Process: [Main](../glossary.md#main-process) + +## Events + +The `memoryPressureMonitor` module emits the following events: + +### Event: 'memory-pressure' + +Returns: + +* `level` string - The memory pressure level. Can be `moderate` or `critical`. + +Emitted when the system reports a change in memory pressure. This is an +OS-level signal indicating that the system is running low on available memory. + +At the `moderate` level, modules should free buffers that are cheap to +re-allocate and not immediately needed. + +At the `critical` level, modules should free all possible memory. The +alternative is to be killed by the system, which means all memory will have to +be re-created, plus the cost of a cold start. + +Apps may react by closing non-essential windows or tabs, clearing caches, +dropping undo history, or other memory-saving measures. + +## Methods + +The `memoryPressureMonitor` module has the following methods: + +### `memoryPressureMonitor.getCurrentPressureLevel()` + +Returns `string` - The current memory pressure level. Can be `none`, `moderate`, +or `critical`. + +Returns the memory pressure level last set via `notifyMemoryPressure()`. Defaults +to `none` if no level has been set. + +### `memoryPressureMonitor.notifyMemoryPressure(level)` + +* `level` string - The pressure level to set. Must be `none`, `moderate`, or + `critical`. + +Broadcasts a memory pressure notification to all listeners in both the main +process and all renderer processes. This causes Chromium internals (blink +resource cache, V8 garbage collector, network cache, decoded image cache, etc.) +to release memory as if the OS had reported memory pressure. + +When called with `none`, the level is stored (so `getCurrentPressureLevel()` +reflects it) but no notification is broadcast, since Chromium does not support +notifying "no pressure". + +Use this when your application knows that external resources held by the +Electron process are causing system-wide memory pressure, and you want Electron +to proactively release caches and run garbage collection across all processes. + +In the main process, this respects the notification-suppressed flag — if +notifications are suppressed (e.g. during memory measurement), the main-process +notification will be silently dropped. Renderer processes are always notified. + +```js +const { memoryPressureMonitor } = require('electron') + +// Listen for OS memory pressure events +memoryPressureMonitor.on('memory-pressure', (level) => { + console.log(`Memory pressure: ${level}`) + if (level === 'critical') { + // Close non-essential windows, drop caches, etc. + } +}) + +// Trigger memory pressure to force Electron to release caches +memoryPressureMonitor.notifyMemoryPressure('critical') + +// Query current pressure level +console.log(memoryPressureMonitor.getCurrentPressureLevel()) +``` diff --git a/docs/api/session.md b/docs/api/session.md index c81cb24dfa3da..8013a42d8f21e 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -49,6 +49,7 @@ of an existing `Session` object. * `options` Object (optional) * `cache` boolean - Whether to enable cache. Default is `true` unless the [`--disable-http-cache` switch](command-line-switches.md#--disable-http-cache) is used. + * `quota` number (optional) - Use a quota size for a partition (in bytes). Returns `Session` - A session instance from the absolute path as specified by the `path` string. When there is an existing `Session` with the same absolute path, it @@ -58,7 +59,11 @@ be thrown if an empty string is provided. To create a `Session` with `options`, you have to ensure the `Session` with the `path` has never been used before. There is no way to change the `options` -of an existing `Session` object. +of an existing `Session` object. The optional `quota` parameter can be used to +specify the a quota size that can be used by the session, which will be returned as the quota provided by navigator.storage.estimate(). If the `quota` is not +provided, the size of the volume on which path is located will be used. A smaller +quota size will allow the LRU algorithm to evict more data from the cache, though there +is no guarantee that the cache will not exceed the quota size. ## Properties diff --git a/docs/api/structures/web-preferences.md b/docs/api/structures/web-preferences.md index e8393585fe6e3..d41881eab07ec 100644 --- a/docs/api/structures/web-preferences.md +++ b/docs/api/structures/web-preferences.md @@ -159,6 +159,14 @@ * `enableDeprecatedPaste` boolean (optional) _Deprecated_ - Whether to enable the `paste` [execCommand](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand). Default is `false`. * `focusOnNavigation` boolean (optional) - Whether to focus the WebContents when navigating. Default is `true`. +* `hideScrollBars` boolean (optional) - Sets the Chromium WebPreferences + hide_scrollbars field. Default is `false`. +* `enablePinchZoom` boolean (optional) - Sets whether to enable pinch to zoom in Chromium. Default is `true`. +* `windowTransform` string (optional) _Linux_ - Specifies whether to apply a transform to the window. Default is `none`. Accepted values are + * `none` - There is no transform (i.e. the widget content is oriented as landscape). + * `rot90` - The widget content is rotated to portrait at 90 degrees (clockwise). + * `rot180` - The widget content is rotated to portrait at 180 degrees (clockwise). + * `rot270` - The widget content is rotated to portrait at 270 degrees (clockwise). [chrome-content-scripts]: https://developer.chrome.com/extensions/content_scripts#execution-environment [runtime-enabled-features]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/platform/runtime_enabled_features.json5 diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 37b35d57dd726..60584c8f45a7e 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -1073,6 +1073,28 @@ Returns: Emitted when the [mainFrame](web-contents.md#contentsmainframe-readonly), an `