diff --git a/README.md b/README.md index f959a404934..fa54b2e65ad 100644 --- a/README.md +++ b/README.md @@ -78,22 +78,22 @@ See the full documentation on [electron.build](https://www.electron.build). * [Auto Update](https://www.electron.build/auto-update) ready application packaging. * Numerous target formats: * All platforms: `7z`, `zip`, `tar.xz`, `tar.7z`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir` (unpacked directory). - * [macOS](https://www.electron.build/configuration/mac): `dmg`, `pkg`, `mas`. - * [Linux](https://www.electron.build/configuration/linux): [AppImage](http://appimage.org), [snap](http://snapcraft.io), debian package (`deb`), `rpm`, `freebsd`, `pacman`, `p5p`, `apk`. - * [Windows](https://www.electron.build/configuration/win): `nsis` (Installer), `nsis-web` (Web installer), `portable` (portable app without installation), AppX (Windows Store), MSI, Squirrel.Windows. -* [Publishing artifacts](https://www.electron.build/configuration/publish) to GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray. + * [macOS](https://www.electron.build/mac): `dmg`, `pkg`, `mas`. + * [Linux](https://www.electron.build/linux): [AppImage](http://appimage.org), [snap](http://snapcraft.io), debian package (`deb`), `rpm`, `freebsd`, `pacman`, `p5p`, `apk`. + * [Windows](https://www.electron.build/win): `nsis` (Installer), `nsis-web` (Web installer), `portable` (portable app without installation), AppX (Windows Store), MSI, Squirrel.Windows. +* [Publishing artifacts](https://www.electron.build/publish) to GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray. * Advanced building: * Pack in a distributable format [already packaged app](https://www.electron.build/#pack-only-in-a-distributable-format). * Separate [build steps](https://github.com/electron-userland/electron-builder/issues/1102#issuecomment-271845854). * Build and publish in parallel, using hard links on CI server to reduce IO and disk space usage. * [electron-compile](https://github.com/electron/electron-compile) support (compile for release-time on the fly on build). * [Docker](https://www.electron.build/multi-platform-build#docker) images to build Electron app for Linux or Windows on any platform. -* [Proton Native](https://www.electron.build/configuration/configuration/#proton-native) support. +* [Proton Native](https://www.electron.build/configuration/#proton-native) support. * Downloads all required tools files on demand automatically (e.g. to code sign windows application, to make AppX), no need to setup. | Question | Answer | | -------------------------------------- | --------------------------------------------------------------------------------- | -| “I want to configure electron-builder” | [See options](https://electron.build/configuration/configuration) | +| “I want to configure electron-builder” | [See options](https://electron.build/configuration) | | “I found a bug or I have a question” | [Open an issue](https://github.com/electron-userland/electron-builder/issues/new) | | “I want to support development” | [Donate](https://www.electron.build/donate) | @@ -140,7 +140,7 @@ will declare to use node-modules instead of PnP. } } ``` - See [all options](https://www.electron.build/configuration/configuration). Option [files](https://www.electron.build/configuration/contents#files) to indicate which files should be packed in the final application, including the entry file, maybe required. + See [all options](https://www.electron.build/configuration). Option [files](https://www.electron.build/contents#files) to indicate which files should be packed in the final application, including the entry file, maybe required. You can also use separate configuration files, such as `js`, `ts`, `yml`, and `json`/`json5`. See [read-config-file](https://www.npmjs.com/package/read-config-file) for supported extensions. [JS Example for programmatic API](https://www.electron.build/api/programmatic-usage) 3. Add [icons](https://www.electron.build/icons). diff --git a/mkdocs.yml b/mkdocs.yml index 99c5810e101..dc8a35a3f33 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,9 +69,10 @@ plugins: # minify_html: true - include-markdown: # encoding: ascii - # preserve_includer_indent: true + preserve_includer_indent: true # dedent: true - # trailing_newlines: true + trailing_newlines: true + # inheritHeadingDepth: true # comments: true rewrite_relative_urls: true # heading_offset: 0 @@ -87,6 +88,7 @@ nav: - Programmatic API: - API: api/electron-builder.md - Example: api/programmatic-usage.md + - Modules: modules.md - Donate: donate.md - Configuration: diff --git a/packages/app-builder-lib/src/index.ts b/packages/app-builder-lib/src/index.ts index 8e92d88ecde..8063d53c584 100644 --- a/packages/app-builder-lib/src/index.ts +++ b/packages/app-builder-lib/src/index.ts @@ -23,7 +23,7 @@ export { export { getArchSuffix, Arch, archFromString } from "builder-util" export { Configuration, AfterPackContext, MetadataDirectories, BeforePackContext, AfterExtractContext, CustomElectronDistributable, Hook } from "./configuration" export { ElectronBrandingOptions, ElectronDownloadOptions, ElectronPlatformName } from "./electron/ElectronFramework" -export { PlatformSpecificBuildOptions, AsarOptions, FileSet, Protocol, ReleaseInfo } from "./options/PlatformSpecificBuildOptions" +export { PlatformSpecificBuildOptions, AsarOptions, FileSet, Protocol, ReleaseInfo, FilesBuildOptions } from "./options/PlatformSpecificBuildOptions" export { FileAssociation } from "./options/FileAssociation" export { MacConfiguration, DmgOptions, MasConfiguration, MacOsTargetName, DmgContent, DmgWindow, NotarizeNotaryOptions } from "./options/macOptions" export { PkgOptions, PkgBackgroundOptions, BackgroundAlignment, BackgroundScaling } from "./options/pkgOptions" diff --git a/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts b/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts index dc35a3d77f6..ad227015978 100644 --- a/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts +++ b/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts @@ -34,7 +34,65 @@ export interface AsarOptions { ordering?: string | null } -export interface PlatformSpecificBuildOptions extends TargetSpecificOptions { +export interface FilesBuildOptions { + /** + * A [glob patterns](./file-patterns.md) relative to the [app directory](configuration.md#MetadataDirectories-app), which specifies which files to include when copying files to create the package. + +Defaults to: +```json +[ + "**\/*", + "!**\/node_modules/*\/{CHANGELOG.md,README.md,README,readme.md,readme}", + "!**\/node_modules/*\/{test,__tests__,tests,powered-test,example,examples}", + "!**\/node_modules/*.d.ts", + "!**\/node_modules/.bin", + "!**\/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}", + "!.editorconfig", + "!**\/._*", + "!**\/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,.gitignore,.gitattributes}", + "!**\/{__pycache__,thumbs.db,.flowconfig,.idea,.vs,.nyc_output}", + "!**\/{appveyor.yml,.travis.yml,circle.yml}", + "!**\/{npm-debug.log,yarn.lock,.yarn-integrity,.yarn-metadata.json}" +] +``` + +Development dependencies are never copied in any case. You don't need to ignore it explicitly. Hidden files are not ignored by default, but all files that should be ignored, are ignored by default. + +Default pattern \`**\/*\` **is not added to your custom** if some of your patterns is not ignore (i.e. not starts with `!`). `package.json` and \`**\/node_modules/**\/*` (only production dependencies will be copied) is added to your custom in any case. All default ignores are added in any case — you don't need to repeat it if you configure own patterns. + +May be specified in the platform options (e.g. in the [mac](mac.md)). + +You may also specify custom source and destination directories by using `FileSet` objects instead of simple glob patterns. + +```json +[ + { + "from": "path/to/source", + "to": "path/to/destination", + "filter": ["**\/*", "!foo/*.js"] + } +] +``` + +You can use [file macros](./file-patterns.md#file-macros) in the `from` and `to` fields as well. `from` and `to` can be files and you can use this to [rename](https://github.com/electron-userland/electron-builder/issues/1119) a file while packaging. + */ + files?: Array | FileSet | string | null + + /** + * A [glob patterns](./file-patterns.md) relative to the project directory, when specified, copy the file or directory with matching names directly into the app's resources directory (`Contents/Resources` for MacOS, `resources` for Linux and Windows). + * + * File patterns (and support for `from` and `to` fields) the same as for [files](#files). + * + */ + extraResources?: Array | FileSet | string | null + + /** + * The same as [extraResources](#extraresources) but copy into the app's content directory (`Contents` for MacOS, root directory for Linux and Windows). + */ + extraFiles?: Array | FileSet | string | null +} + +export interface PlatformSpecificBuildOptions extends TargetSpecificOptions, FilesBuildOptions { /** * The application id. Used as [CFBundleIdentifier](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102070) for MacOS and as * [Application User Model ID](https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx) for Windows (NSIS target only, Squirrel.Windows not supported). It is strongly recommended that an explicit ID is set. @@ -65,10 +123,6 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions { */ disableDefaultIgnoredFiles?: boolean | null - files?: Array | FileSet | string | null - extraResources?: Array | FileSet | string | null - extraFiles?: Array | FileSet | string | null - /** * Whether to package the application's source code into an archive, using [Electron's archive format](http://electron.atom.io/docs/tutorial/application-packaging/). * diff --git a/packages/app-builder-lib/templates/nsis/README.md b/packages/app-builder-lib/templates/nsis/README.md index 62b793f2851..4749f174306 100644 --- a/packages/app-builder-lib/templates/nsis/README.md +++ b/packages/app-builder-lib/templates/nsis/README.md @@ -1,6 +1,6 @@ # NSIS -⚠️ **It is developer documentation.** If your are looking for usage guide, see [user documentation](https://electron.build/configuration/nsis). +⚠️ **It is developer documentation.** If your are looking for usage guide, see [user documentation](https://electron.build/nsis). NSIS stands for Nullsoft Scriptable Install System. electron-builder utilizes a [customized version](https://github.com/electron-userland/electron-builder-binaries) of it and uses `NsisMultiUser` plugin to handle installation for single user or all users on the computer. @@ -24,7 +24,7 @@ For translators, the strings to be displayed are included in [`assistedMessages. As for other strings in NSIS, head to [electron-userland/electron-builder-binaries](https://github.com/electron-userland/electron-builder-binaries) or the upstream repository on [Sorceforge](https://sourceforge.net/p/nsis/code/HEAD/tree/). ## GUID -See [docs](https://electron.build/configuration/nsis). +See [docs](https://electron.build/nsis). We use UUID v5 to generate sha-1 name-based UUID. diff --git a/packages/electron-forge-maker-appimage/readme.md b/packages/electron-forge-maker-appimage/readme.md index c65cc78e7df..854537bc964 100644 --- a/packages/electron-forge-maker-appimage/readme.md +++ b/packages/electron-forge-maker-appimage/readme.md @@ -3,7 +3,7 @@ [electron-builder](https://github.com/electron-userland/electron-builder) [appimage](http://appimage.org) target for electron-forge. Recommended to build electron-forge project using electron-builder directly. -[Publishing](https://www.electron.build/configuration/publish), +[Publishing](https://www.electron.build/publish), [Auto Update](https://electron.build/auto-update) and [Code Signing](https://electron.build/code-signing) supported only in this case -(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file +(including all other useful [packaging options](https://electron.build/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file diff --git a/packages/electron-forge-maker-nsis-web/readme.md b/packages/electron-forge-maker-nsis-web/readme.md index c837e96bd9d..6bf2f0a2eb6 100644 --- a/packages/electron-forge-maker-nsis-web/readme.md +++ b/packages/electron-forge-maker-nsis-web/readme.md @@ -1,9 +1,9 @@ # electron-forge-maker-nsis-web -[electron-builder](https://github.com/electron-userland/electron-builder) [nsis-web](https://electron.build/configuration/nsis) target for electron-forge. +[electron-builder](https://github.com/electron-userland/electron-builder) [nsis-web](https://electron.build/nsis) target for electron-forge. Recommended to build electron-forge project using electron-builder directly. -[Publishing](https://www.electron.build/configuration/publish), +[Publishing](https://www.electron.build/publish), [Auto Update](https://electron.build/auto-update) and [Code Signing](https://electron.build/code-signing) supported only in this case -(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file +(including all other useful [packaging options](https://electron.build/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file diff --git a/packages/electron-forge-maker-nsis/readme.md b/packages/electron-forge-maker-nsis/readme.md index c0e27581ae2..07fdfe8c385 100644 --- a/packages/electron-forge-maker-nsis/readme.md +++ b/packages/electron-forge-maker-nsis/readme.md @@ -1,9 +1,9 @@ # electron-forge-maker-nsis -[electron-builder](https://github.com/electron-userland/electron-builder) [nsis](https://electron.build/configuration/nsis) target for electron-forge. +[electron-builder](https://github.com/electron-userland/electron-builder) [nsis](https://electron.build/nsis) target for electron-forge. Recommended to build electron-forge project using electron-builder directly. -[Publishing](https://www.electron.build/configuration/publish), +[Publishing](https://www.electron.build/publish), [Auto Update](https://electron.build/auto-update) and [Code Signing](https://electron.build/code-signing) supported only in this case -(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file +(including all other useful [packaging options](https://electron.build/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file diff --git a/packages/electron-forge-maker-snap/readme.md b/packages/electron-forge-maker-snap/readme.md index 1a2dae28983..1789a949756 100644 --- a/packages/electron-forge-maker-snap/readme.md +++ b/packages/electron-forge-maker-snap/readme.md @@ -3,7 +3,7 @@ [electron-builder](https://github.com/electron-userland/electron-builder) [snap](https://snapcraft.io) target for electron-forge. Recommended to build electron-forge project using electron-builder directly. -[Publishing](https://www.electron.build/configuration/publish), +[Publishing](https://www.electron.build/publish), [Auto Update](https://electron.build/auto-update) and [Code Signing](https://electron.build/code-signing) supported only in this case -(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file +(including all other useful [packaging options](https://electron.build/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file diff --git a/packages/electron-publish/readme.md b/packages/electron-publish/readme.md index 25a22a0a2ab..d26508a5c03 100644 --- a/packages/electron-publish/readme.md +++ b/packages/electron-publish/readme.md @@ -1,7 +1,7 @@ # electron-publish -Part of [electron-builder](https://github.com/electron-userland/electron-builder). +Part of [electron-builder](https://github.com/electron-userland/electron-builder). -See the [Publishing Artifacts](https://www.electron.build/configuration/publish) for more information. +See the [Publishing Artifacts](https://www.electron.build/publish) for more information. Can be used standalone. \ No newline at end of file diff --git a/pages/api/programmatic-usage.md b/pages/api/programmatic-usage.md index fc4883cba83..6db93c98cca 100644 --- a/pages/api/programmatic-usage.md +++ b/pages/api/programmatic-usage.md @@ -7,7 +7,7 @@ const Platform = builder.Platform // Let's get that intellisense working /** * @type {import('electron-builder').Configuration} -* @see https://www.electron.build/configuration/configuration +* @see https://www.electron.build/configuration */ const options = { protocols: { @@ -17,11 +17,11 @@ const options = { "deeplink" ] }, - + // "store” | “normal” | "maximum". - For testing builds, use 'store' to reduce build time significantly. compression: "normal", removePackageScripts: true, - + afterSign: async (context) => { // Mac releases require hardening+notarization: https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution if (!isDebug && context.electronPlatformName === "darwin") { @@ -42,7 +42,7 @@ const options = { }, nodeGypRebuild: false, buildDependenciesFromSource: false, - + directories: { output: "dist/artifacts/local", buildResources: "installer/resources" @@ -57,7 +57,7 @@ const options = { filter: "*.node" } ], - + win: { target: 'nsis' }, @@ -65,7 +65,7 @@ const options = { deleteAppDataOnUninstall: true, include: "installer/win/nsis-installer.nsh" }, - + mac: { target: 'dmg', hardenedRuntime: true, @@ -97,7 +97,7 @@ const options = { height: 500 } }, - + linux: { desktop: { StartupNotify: "false", diff --git a/pages/contents.md b/pages/contents.md index 85a4d6691c7..2848da0631b 100644 --- a/pages/contents.md +++ b/pages/contents.md @@ -1,61 +1,7 @@ -## files +# File Contents -`Array | String | FileSet` - -A [glob patterns](./file-patterns.md) relative to the [app directory](configuration.md#MetadataDirectories-app), which specifies which files to include when copying files to create the package. - -Defaults to: -```json -[ - "**/*", - "!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}", - "!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}", - "!**/node_modules/*.d.ts", - "!**/node_modules/.bin", - "!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}", - "!.editorconfig", - "!**/._*", - "!**/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,.gitignore,.gitattributes}", - "!**/{__pycache__,thumbs.db,.flowconfig,.idea,.vs,.nyc_output}", - "!**/{appveyor.yml,.travis.yml,circle.yml}", - "!**/{npm-debug.log,yarn.lock,.yarn-integrity,.yarn-metadata.json}" -] -``` - -Development dependencies are never copied in any case. You don't need to ignore it explicitly. Hidden files are not ignored by default, but all files that should be ignored, are ignored by default. - -Default pattern `**/*` **is not added to your custom** if some of your patterns is not ignore (i.e. not starts with `!`). `package.json` and `**/node_modules/**/*` (only production dependencies will be copied) is added to your custom in any case. All default ignores are added in any case — you don't need to repeat it if you configure own patterns. - -May be specified in the platform options (e.g. in the [mac](mac.md)). - -You may also specify custom source and destination directories by using `FileSet` objects instead of simple glob patterns. - -```json -[ - { - "from": "path/to/source", - "to": "path/to/destination", - "filter": ["**/*", "!foo/*.js"] - } -] -``` - -You can use [file macros](../file-patterns.md#file-macros) in the `from` and `to` fields as well. `from` and `to` can be files and you can use this to [rename](https://github.com/electron-userland/electron-builder/issues/1119) a file while packaging. - -## extraResources - -`Array | String | FileSet` - -A [glob patterns](../file-patterns.md) relative to the project directory, when specified, copy the file or directory with matching names directly into the app's resources directory (`Contents/Resources` for MacOS, `resources` for Linux and Windows). - -File patterns (and support for `from` and `to` fields) the same as for [files](#files). - -## extraFiles - -`Array | String | FileSet` - -The same as [extraResources](#extraresources) but copy into the app's content directory (`Contents` for MacOS, root directory for Linux and Windows). +{% include-markdown "./app-builder-lib.Interface.FilesBuildOptions.md" heading-offset=1 %} # FileSet Configuration -{% include "./app-builder-lib.Interface.FileSet.md" %} \ No newline at end of file +{% include-markdown "./app-builder-lib.Interface.FileSet.md" heading-offset=2 %} \ No newline at end of file diff --git a/pages/modules.md b/pages/modules.md new file mode 100644 index 00000000000..36cd5fb05cd --- /dev/null +++ b/pages/modules.md @@ -0,0 +1,12 @@ +{% include "./app-builder-lib/globals.md" %} +{% include "./builder-util-runtime/globals.md" %} +{% include "./builder-util/globals.md" %} +{% include "./dmg-builder/globals.md" %} +{% include "./electron-builder-squirrel-windows/globals.md" %} +{% include "./electron-builder/globals.md" %} +{% include "./electron-forge-maker-appimage/globals.md" %} +{% include "./electron-forge-maker-nsis-web/globals.md" %} +{% include "./electron-forge-maker-nsis/globals.md" %} +{% include "./electron-forge-maker-snap/globals.md" %} +{% include "./electron-publish/globals.md" %} +{% include "./electron-updater/globals.md" %} diff --git a/typedoc.config.js b/typedoc.config.js index 5ccec18f10f..2542088f690 100644 --- a/typedoc.config.js +++ b/typedoc.config.js @@ -6,17 +6,23 @@ module.exports = { name: "Electron-Builder", entryPoints: ["packages/*"], entryPointStrategy: "packages", - includeVersion: true, cleanOutputDir: false, flattenOutputFiles: true, plugin: [ "typedoc-plugin-markdown", - // "./scripts/renderer/out/src/customRendererPlugin.js", + // "./scripts/renderer/out/customRendererPlugin.js", ], - hideGroupHeadings: false, + excludeExternals: true, + excludePrivate: true, + excludeProtected: true, + excludeNotDocumented: true, + includeVersion: false, + hideGroupHeadings: true, hidePageTitle: true, disableSources: true, - hidePageHeader: false, + hidePageHeader: true, + sort: ["required-first"], + categorizeByGroup: true, // indexFormat: "table", // parametersFormat: "table", // interfacePropertiesFormat: "table",