|
| 1 | +--- |
| 2 | +title: Debugging |
| 3 | +order: 350 |
| 4 | +--- |
| 5 | + |
| 6 | +# When things go wrong |
| 7 | + |
| 8 | +Building native applications is a complex task with many moving parts. There will be errors, crashes and lots of |
| 9 | +head-scratching. |
| 10 | + |
| 11 | +NativePHP works to hide much of the complexity, but sometimes you will need go under the hood to find out what's really |
| 12 | +going on. |
| 13 | + |
| 14 | +**Remember that NativePHP is a relatively thin layer above a whole ocean of dependencies and tools that are built and |
| 15 | +maintained by many developers outside the NativePHP team.** |
| 16 | + |
| 17 | +This means that while some issues can be solved within NativePHP it's also very likely that the problem lies elsewhere. |
| 18 | + |
| 19 | +## The layers |
| 20 | + |
| 21 | +- Your application, built on Laravel, using your local installations of PHP & Node. |
| 22 | +- NativePHP's development tools (`native:serve` and `native:build`) manage the Electron/Tauri build processes - this is |
| 23 | + what creates your Application Bundle. |
| 24 | +- NativePHP moves the appropriate version of a statically-compiled binary of PHP into your application's bundle - when |
| 25 | + your app boots, it's _this_ version of PHP that is being used to execute your PHP code, not your system's version of |
| 26 | + PHP. |
| 27 | +- Electron & Tauri use suites of platform-specific build tools and dependencies - Electron's ecosystem is mostly |
| 28 | + Javascript based, Tauri's is mostly Rust based. Much of this will be hidden away in your `vendor` directory. |
| 29 | +- The operating system (OS) and its architecture (arch) - you can't build an application for one architecture and |
| 30 | + distribute it to a different OS/arch. It won't work. You must build your application to match the OS+arch combination |
| 31 | + where you want it to run. |
| 32 | + |
| 33 | +While you are not expected to know in-depth how all of these layers work and fit together, some familiarity with what's |
| 34 | +going on will help you find the root cause of issues and be able to raise meaningful tickets with the right people. |
| 35 | + |
| 36 | +## Doing some digging |
| 37 | + |
| 38 | +Here are some tips for debugging: |
| 39 | + |
| 40 | +### Two or three copies |
| 41 | +Remember that when a build is generated (dev or prod), your whole Laravel application is _copied into_ the build folder. |
| 42 | + |
| 43 | +The dev build copy is stored in `vendor` (holy inception, Batman!). |
| 44 | + |
| 45 | +Prod builds get packed in the `dist` folder. |
| 46 | + |
| 47 | +This means there are at least 2 versions of your code that could be running depending on what you're doing: the hot code |
| 48 | +that you edit in your IDE (your 'development environment') and the bundle code that actually gets executed when your app |
| 49 | +runs in either a dev build or a prod build. |
| 50 | + |
| 51 | +Having a clear understanding about what context you're in when issues occur will help you to solve the problem faster. |
| 52 | + |
| 53 | +### Verbose output |
| 54 | +Use `-v`, `-vv` or `-vvv` when running `native:serve` or `native:build` as this will provide more detail as to what's |
| 55 | +happening at each stage of a process. |
| 56 | + |
| 57 | +### Check the logs |
| 58 | +Logs generated by running builds of your application are stored in `{appdata}/storage/logs/`. |
| 59 | + |
| 60 | +Logs generated when running Artisan commands in your development environment are in `storage/logs/` (default Laravel). |
| 61 | + |
| 62 | +### Step out |
| 63 | +Try running a step _outside_ of the runtime environment - reduce the layers to rule out environment-specific complications. |
| 64 | + |
| 65 | +### Start from scratch |
| 66 | +Don't be afraid to delete builds and start again! The `dist` folder in your application's root may sometimes get into |
| 67 | +an unusual state and just needs wiping out. |
| 68 | + |
| 69 | +Make sure there are no lingering processes - check your Activity Monitor/Task Manager to find stray processes that may |
| 70 | +hang around after a build has failed, and force them to quit. |
| 71 | + |
| 72 | +### Check your app and PHP |
| 73 | +Errors that occur in PHP execution during the application's bootup sequence can cause the app to crash before it even |
| 74 | +starts. |
| 75 | + |
| 76 | +A 500 error in your application code, for example, may prevent the main window from showing, but would leave the runtime's |
| 77 | +shell process running. |
| 78 | + |
| 79 | +Try booting your application in a standard browser to see if there are any errors when hitting its entrypoint URL. If |
| 80 | +you're using Laravel Herd, for example, move your app development environment into your Herd root folder and go to |
| 81 | +`http://{your-app-folder-name}.test/` in your favorite browser. |
| 82 | + |
| 83 | +Also make sure that the PHP version in the bundle is the same as the one you have installed on your machine |
| 84 | + |
| 85 | +If you're running PHP8.2 on your machine, the PHP binary that is moved into the `dist` folder should be PHP8.2 for your |
| 86 | +current OS+arch. You can check this in the CLI: |
| 87 | + |
| 88 | +#### For dev builds: |
| 89 | +M-series (ARM) Mac: |
| 90 | +```shell |
| 91 | +/path/to/your/app/vendor/nativephp/electron/resources/js/resources/php/php -v |
| 92 | +``` |
| 93 | +Windows: |
| 94 | +```shell |
| 95 | +C:\path\to\your\app\vendor\nativephp\resources\js\resources\php\php.exe -v |
| 96 | +``` |
| 97 | + |
| 98 | +#### For production builds: |
| 99 | +M-series (ARM) Mac computer: |
| 100 | +```shell |
| 101 | +/path/to/your/app/dist/mac-arm/AppName/Contents/Resources/app.asar.unpacked/resources/php/php -v |
| 102 | +``` |
| 103 | + |
| 104 | +Windows: |
| 105 | +```shell |
| 106 | +C:\path\to\your\app\dist\win-unpacked\resources\app.asar.unpacked\resources\php\php.exe -v |
| 107 | +``` |
0 commit comments