diff --git a/BUILD.md b/BUILD.md index 5b32bc7dd..e7ed1cb6a 100644 --- a/BUILD.md +++ b/BUILD.md @@ -22,19 +22,6 @@ Then you can test the various applications: cd ElectronClient npm start -If you'd like to auto-reload the app on changes rather than having to quit and restart it manually each time, you can use [watchman-make](https://facebook.github.io/watchman/docs/watchman-make.html): - -```sh -cd ElectronClient -watchman-make -p '**/*.js' '**/*.jsx' --run "npm start" -``` - -It still requires you to quit the application each time you want it to rebuild, but at least you don't have to re-run `"npm start"` each time. Here's what the workflow loop looks like in practice: - -1. Edit and save files in your text editor. -2. Switch to the Electron app and cmd+Q to quit it. -3. `watchman` immediately restarts the app for you (whereas usually you'd have to switch back to the terminal, type `"npm start"`, and hit enter). - ## Testing the Terminal application cd CliClient @@ -52,7 +39,7 @@ Then: To run the iOS application, it might be easier to open the file `ios/Joplin.xcworkspace` on XCode and run the app from there. -Normally the bundler should start automatically with the application. If it doesn't run `npm start`. +Normally the bundler should start automatically with the application. If it doesn't, run `npm start`. ## Building the clipper @@ -80,37 +67,21 @@ You can specify additional parameters when running the desktop or CLI applicatio Most of the application is written in JavaScript, however new classes and files should generally be written in [TypeScript](https://www.typescriptlang.org/). All TypeScript files are generated next to the .ts or .tsx file. So for example, if there's a file "lib/MyClass.ts", there will be a generated "lib/MyClass.js" next to it. It is implemented that way as it requires minimal changes to integrate TypeScript in the existing JavaScript code base. -# Troubleshooting desktop application +## Hot reload -## On Linux and macOS +If you'd like to auto-reload the desktop app on changes rather than having to quit and restart it manually each time, you can use [watchman-make](https://facebook.github.io/watchman/docs/watchman-make.html): -If there's an error `while loading shared libraries: libgconf-2.so.4: cannot open shared object file: No such file or directory`, run `sudo apt-get install libgconf-2-4` +```sh +cd ElectronClient +watchman-make -p '**/*.js' '**/*.jsx' --run "npm start" +``` -If you get a node-gyp related error, you might need to manually install it: `npm install -g node-gyp`. +It still requires you to quit the application each time you want it to rebuild, but at least you don't have to re-run `"npm start"` each time. Here's what the workflow loop looks like in practice: -If you get the error `libtool: unrecognized option '-static'`, follow the instructions [in this post](https://stackoverflow.com/a/38552393/561309) to use the correct libtool version. +1. Edit and save files in your text editor. +2. Switch to the Electron app and cmd+Q to quit it. +3. `watchman` immediately restarts the app for you (whereas usually you'd have to switch back to the terminal, type `"npm start"`, and hit enter). -## On Windows +# Troubleshooting -If node-gyp does not work (MSBUILD: error MSB3428: Could not load the Visual C++ component "VCBuild.exe"), you might need to install `windows-build-tools` using `npm install --global windows-build-tools`. - -If `yarn dist` fails, it may need administrative rights. - -If you get an `error MSB8020: The build tools for v140 cannot be found.` try to run with a different toolset version, eg `npm install --toolset=v141` (See [here](https://github.com/mapbox/node-sqlite3/issues/1124) for more info). - -## Other issues - -> The application window doesn't open or is white - -This is an indication that there's an early initialisation error. Try this: - -- In ElectronAppWrapper, set `debugEarlyBugs` to `true`. This will force the window to show up and should open the console next to it, which should display any error. -- In more rare cases, an already open instance of Joplin can create strange low-level bugs that will display no error but will result in this white window. A non-dev instance of Joplin, or a dev instance that wasn't properly closed might cause this. So make sure you close everything and try again. Perhaps even other Electron apps running (Skype, Slack, etc.) could cause this? -- Also try to delete node_modules and rebuild. -- If all else fails, switch your computer off and on again, to make sure you start clean. - -> How to work on the app from Windows? - -**You should not use WSL at all** because this is a GUI app that lives outside of WSL, and the WSL layer can cause all kind of very hard to debug issues. It can also lock files in node_modules that cannot be unlocked when the app crashes. (You need to restart your computer.) Likewise, don't run the TypeScript watch command from WSL. - -So everything should be done from a Windows Command prompt or Windows PowerShell running as Administrator. All build and start commands are designed to work cross-platform, including on Windows. +Please read for the [Build Troubleshooting Document](https://github.com/laurent22/joplin/blob/master/readme/build_troubleshooting.md) for various tips on how to get the build working. \ No newline at end of file diff --git a/readme/build_troubleshooting.md b/readme/build_troubleshooting.md new file mode 100644 index 000000000..dbea03dbd --- /dev/null +++ b/readme/build_troubleshooting.md @@ -0,0 +1,39 @@ +# Desktop application + +## Windows + +If `yarn dist` fails, it may need administrative rights. + +If you get an `error MSB8020: The build tools for v140 cannot be found.` try to run with a different toolset version, eg `npm install --toolset=v141` (See [here](https://github.com/mapbox/node-sqlite3/issues/1124) for more info). You may also try to install `npm --vs2015 install --global windows-build-tools` (the --vs2015 flag is to get toolkit "v140", which is what is used by default). + +There are various errors that can occur from an improper build environment (such as MSBUILD: error MSB3428). It is recommended to install `windows-build-tools` with the command `npm install --global windows-build-tools` (elevation required) and then using these two commands to set the environmental variables to the proper values: + +```batch +call "C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Auxiliary\Build\vcvarsamd64_x86.bat" +set "PATH=C:\Program Files\nodejs;%PATH%" +``` + +## On Linux and macOS + +If there's an error `while loading shared libraries: libgconf-2.so.4: cannot open shared object file: No such file or directory`, run `sudo apt-get install libgconf-2-4` + +If you get a node-gyp related error, you might need to manually install it: `npm install -g node-gyp`. + +If you get the error `libtool: unrecognized option '-static'`, follow the instructions [in this post](https://stackoverflow.com/a/38552393/561309) to use the correct libtool version. + +## Other issues + +> The application window doesn't open or is white + +This is an indication that there's an early initialisation error. Try this: + +- In ElectronAppWrapper, set `debugEarlyBugs` to `true`. This will force the window to show up and should open the console next to it, which should display any error. +- In more rare cases, an already open instance of Joplin can create strange low-level bugs that will display no error but will result in this white window. A non-dev instance of Joplin, or a dev instance that wasn't properly closed might cause this. So make sure you close everything and try again. Perhaps even other Electron apps running (Skype, Slack, etc.) could cause this? +- Also try to delete node_modules and rebuild. +- If all else fails, switch your computer off and on again, to make sure you start clean. + +> How to work on the app from Windows? + +**You should not use WSL at all** because this is a GUI app that lives outside of WSL, and the WSL layer can cause all kind of very hard to debug issues. It can also lock files in node_modules that cannot be unlocked when the app crashes. (You need to restart your computer.) Likewise, don't run the TypeScript watch command from WSL. + +So everything should be done from a Windows Command prompt or Windows PowerShell running as Administrator. All build and start commands are designed to work cross-platform, including on Windows. \ No newline at end of file diff --git a/readme/building_win32_tips.md b/readme/building_win32_tips.md deleted file mode 100644 index d9d639a35..000000000 --- a/readme/building_win32_tips.md +++ /dev/null @@ -1,127 +0,0 @@ -* * * - -**IMPORTANT: The build system has been changed since this document was written, thus it contains outdated information. It is kept for now as it may still contain some tips on how to get things working.** - -* * * - -## Building Joplin on Windows - -Building on Windows involved a few more steps for me, so I thought I'd leave some tips here in case they are helpful for others. - -Use an "admin" command prompt when running the following. A quick way to open an admin command prompt is to press Windows-X, and then click on Command Prompt-Admin from the menu. - -If you don't already have Node, - -* Install Node from [here](https://nodejs.org/en/); one typically chooses the version labeled "LTS". - -If you don't already have Yarn, - -* Install Yarn from [here](https://yarnpkg.com/lang/en/docs/install/#windows-stable); I clicked Download Installer and ran the .msi to install. - -Run the following from an admin prompt, - -* Run `npm --vs2015 install --global windows-build-tools` - -* I got a message saying that the installation succeeded, except that it "failed to install python 2.7". If you receive this error, you can install python 2.7 from [here](https://www.python.org/downloads/release/python-2715/) - -* (the --vs2015 flag is needed because we want to have toolkit "v140", the default version is "v141", which comes with Visual Studio 2017. another way to install the v140 toolkit is to install ["build tools for visual studio"](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017), click Install/modify under Build Tools in the upper left corner, then on the next screen, check the box for "VS 2015 tools" in the tree of options on the right, then click Install.) - -* Run `npm install --global node-gyp` - -* Run `cd c:\path\to\joplin` - -* Run `cd ElectronClient` - -* Run `xcopy /C /I /H /R /Y /S ..\..\ReactNativeClient\lib lib` - -* if you got the error message about python 2.7, like I did, I had to set these environment variables, to point the build scripts to python. `set path=%path%;C:\python27` and `set PYTHON=C:\python27\python.exe` - -* Run `npm install` - -* Run `yarn dist` - -* (I see this error in the cleanup phase, but it doesn't seem to affect building Joplin itself.) `Error: ENOENT: no such file or directory, copyfile 'C:\Users\...\AppData\Local\electron-builder\cache\nsis\nsis-3.0.3.0\elevate.exe' -> 'C:\...\joplin\joplin\ElectronClient\app\dist\win-unpacked\resources\elevate.exe' - at doCopyFile (C:\...\joplin\ElectronClient\app\node_modules\builder-util\src\fs.ts:204:19)` - -* Done: you can now run `ElectronClient\app\dist\win-unpacked\Joplin.exe` - -## Running + debugging Joplin - -Run the following from any cmd.exe prompt, doesn't need to be admin, - -* Run `cd c:\path\to\joplin` - -* Run `cd ElectronClient` - -* Create a profile directory for testing, for example `mkdir c:\path\to\test_profile_dir` - -* Run `.\node_modules\.bin\electron.cmd . --env dev --open-dev-tools --log-level debug --profile c:\path\to\test_profile_dir` - -* Joplin will open with a chromium debug panel visible, console logging will appear there, and you can even set breakpoints/step through code. - -* It can also be useful to look at `test_profile_dir\logs.txt` and see log statements. - -* (Note: it doesn't work to use symlinks like `mklink /d` so that every "lib" directory points to the same location. this causes an error dialog when running electron saying that sprintf-js could not be loaded). - -## Running tests - -Run the following from any cmd.exe prompt, doesn't need to be admin, - -* Run `cd c:\path\to\joplin` - -* Run `cd CliClient` - -* Run `npm install` - -* (important) run `mkdir tests-build\data` - -* Run `xcopy /C /I /H /R /Y /S .\tests .\tests-build` (we're following the actions in `run_test.sh`) - -* Run `xcopy /C /I /H /R /Y /S ..\ReactNativeClient\lib tests-build\lib` - -* Run `xcopy /C /I /H /R /Y /S ..\ReactNativeClient\locales tests-build\locales` - -You should now be able to run any of the tests, such as `npm test tests-build/ArrayUtils.js` - -This also works, which can be useful for attaching a debugger: `node ./node_modules/jasmine/bin/jasmine.js tests-build/ArrayUtils.js` - -## Running tests in VSCode - -* It's not the most elegant, but I put this together for running a test in vscode with breakpoint and debugging, - -* Run the steps above for "Running tests" - -* Create the file tests-build/.vscode/launch.json - -* Place the following contents into launch.json, - - { - "version": "0.2.0", - "configurations": [ - { - "type": "node", - "request": "launch", - "name": "joplin jasmine test", - "cwd": "${workspaceFolder}", - "runtimeExecutable": "node", - "runtimeArgs": ["--inspect-brk", - "../node_modules/jasmine/bin/jasmine.js", - "../tests-build/ArrayUtils.js"], - "protocol": "inspector", - "port": 9229, - "smartStep": true, - "skipFiles": [ - "${workspaceRoot}/../node_modules/**/*.js", - "/**" - ], - } - ] - } - -* (the smartStep and skipFiles make it much cleaner to step into an `await` call.) - -* If you're debugging a test other than ArrayUtils.js, edit launch.json and replace the reference to ArrayUtils.js with another script - -* Open VSCode, File->Open Folder, and open the `tests-build` folder. (you have to use *Open Folder* for this to work). - -* Set a breakpoint in the test's code. Debug->Start Debugging (F5) will run the test and hit the breakpoints.