scratch-desktop/README.md

136 lines
5.3 KiB
Markdown
Raw Normal View History

# scratch-desktop
2017-08-27 16:58:13 -04:00
Scratch 3.0 as a standalone desktop application
2018-12-27 15:18:04 -05:00
## Developer Instructions
### Prepare `scratch-gui`
This step is temporary: eventually, the `scratch-desktop` branch of the Scratch GUI repository will be merged with
that repository's main development line. For now, though, the `scratch-desktop` branch holds a few changes that are
necessary for Scratch Desktop to function correctly but are not yet merged into the main development branch.
#### Prepare `scratch-gui`: Quick Start
1. Clone both `scratch-desktop` and `scratch-gui`
2. `cd scratch-gui`
1. `git checkout scratch-desktop`
2. `npm install`
3. `npm link`
4. `cd ..`
3. `cd scratch-desktop`
1. `npm install`
2. `npm link scratch-gui`
3. `npm run build-gui` or `npm run watch-gui`
Your copy of `scratch-gui` should now be ready for use with Scratch Desktop.
#### Prepare `scratch-gui`: Detailed Version
2018-12-27 15:18:04 -05:00
1. Clone the `scratch-gui` repository if you haven't already.
2. Switch to the `scratch-desktop` branch with `git checkout scratch-desktop`
3. Build with `BUILD_MODE=dist` and `STATIC_PATH=static`:
- macOS, WSL, or Cygwin: run `BUILD_MODE=dist STATIC_PATH=static npm run build` or
`BUILD_MODE=dist STATIC_PATH=static npm run watch`
- Running `npm run build-gui` in `scratch-desktop` is a shortcut for this when using `npm link`.
- CMD: run `set BUILD_MODE=dist` once and `set STATIC_PATH=static` once, then `npm run build` or `npm run watch`
any number of times in the same
2018-12-27 15:18:04 -05:00
window.
- PowerShell: run `$env:BUILD_MODE = "dist"` once and `$env:STATIC_PATH = "static"` once, then `npm run build` or
`npm run watch` any number of times in the same window.
If you have run `npm link scratch-gui` (or equivalent) in the `scratch-desktop` working directory, you may be able to
accomplish the above by running `npm run build-gui` in the `scratch-desktop` directory instead of using the manual
steps listed above. For active development iteration, try `npm run watch-gui` which will watch for changes and rebuild
`scratch-gui` incrementally when necessary.
2018-12-27 15:18:04 -05:00
### Prepare media library assets
In the `scratch-desktop` directory, run `npm run fetch`. Re-run this any time you update `scratch-gui` or make any
other changes which might affect the media libraries.
### Run in development mode
`npm start`
### Make a packaged build
`npm run dist`
Node that on macOS this will require installing various certificates.
#### Signing the NSIS installer (Windows, non-store)
*This section is relevant only to members of the Scratch Team.*
By default all Windows installers are unsigned. An APPX package for the Microsoft Store shouldn't be signed: it will
be signed automatically as part of the store submission process. On the other hand, the non-Store NSIS installer
should be signed.
To generate a signed NSIS installer:
1. Acquire our latest digital signing certificate and save it on your computer as a `p12` file.
2. Set `WIN_CSC_LINK` to the path to your certificate file. For maximum compatibility I use forward slashes.
- CMD: `set WIN_CSC_LINK=C:/Users/You/Somewhere/Certificate.p12`
- PowerShell: `$env:WIN_CSC_LINK = "C:/Users/You/Somewhere/Certificate.p12"`
3. Set `WIN_CSC_KEY_PASSWORD` to the password string associated with your P12 file.
- CMD: `set WIN_CSC_KEY_PASSWORD=superSecret`
- PowerShell: `$env:WIN_CSC_KEY_PASSWORD = "superSecret"`
4. Build the NSIS installer only: building the APPX installer will fail if these environment variables are set.
- `npm run dist -- -w nsis`
#### Workaround for code signing issue in macOS
Sometimes the macOS build process will result in a build which crashes on startup. If this happens, check in `Console`
for an entry similar to this:
```text
failed to parse entitlements for Scratch Desktop[12345]: OSUnserializeXML: syntax error near line 1
```
This appears to be an issue with `codesign` itself. Rebooting your computer and trying to build again might help. Yes,
really.
See this issue for more detail: <https://github.com/electron/electron-osx-sign/issues/218>
2018-12-27 15:18:04 -05:00
### Make a semi-packaged build
This will simulate a packaged build without actually packaging it: instead the files will be copied to a subdirectory
of `dist`.
`npm run dist:dir`
### Debugging
You can debug the renderer process by opening the Chromium development console. This should be the same keyboard
shortcut as Chrome on your platform. This won't work on a packaged build.
You can debug the main process the same way as any Node.js process. I like to use Visual Studio Code with a
configuration like this:
```jsonc
2018-12-27 15:18:04 -05:00
"launch": {
"version": "0.2.0",
"configurations": [
{
"name": "Desktop",
"type": "node",
"request": "launch",
"cwd": "${workspaceFolder:scratch-desktop}",
"runtimeExecutable": "npm",
"autoAttachChildProcesses": true,
"runtimeArgs": ["start", "--"],
"protocol": "inspector",
"skipFiles": [
// it seems like skipFiles only reliably works with 1 entry :(
//"<node_internals>/**",
"${workspaceFolder:scratch-desktop}/node_modules/electron/dist/resources/*.asar/**"
],
"sourceMaps": true,
"timeout": 30000,
"outputCapture": "std"
}
]
},
```