Skip to content

Commit 712b7ea

Browse files
committed
Add more debugging info
1 parent d45aa91 commit 712b7ea

File tree

1 file changed

+45
-9
lines changed

1 file changed

+45
-9
lines changed

resources/views/docs/1/getting-started/debugging.md

Lines changed: 45 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -60,17 +60,44 @@ Logs generated by running builds of your application are stored in `{appdata}/st
6060
Logs generated when running Artisan commands in your development environment are in `storage/logs/` (default Laravel).
6161

6262
### Step out
63-
Try running a step _outside_ of the runtime environment - reduce the layers to rule out environment-specific complications.
63+
Try running the step that's failing _outside_ of the runtime environment. Reduce the layers of abstraction to
64+
identify or rule out environment-specific complications.
6465

6566
### Start from scratch
67+
68+
#### `dist`
6669
Don't be afraid to delete builds and start again! The `dist` folder in your application's root may sometimes get into
6770
an unusual state and just needs wiping out.
6871

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.
72+
#### AppData
73+
The appdata directory is where your application's database, logs, and other application-specific items are stored.
74+
This is a reliable place to store data and files that your application needs to function _outside_ of the app
75+
bundle and without cluttering your user's home directory or other personal folders.
76+
77+
When testing prod builds, the appdata directory will be created on your machine, allowing you to fully mimic an end-user
78+
experience.
79+
80+
In some cases, you may need to wipe this folder and then re-run your app.
81+
82+
| Platform | Location |
83+
|----------|--------------------------------|
84+
| macOS | ~/Library/Application Support |
85+
| Linux | $XDG_CONFIG_HOME or ~/.config |
86+
| Windows | %APPDATA% |
87+
88+
#### Database
89+
Try [completely refreshing](/docs/digging-deeper/databases#refreshing-your-app-database) your app's prod database:
90+
91+
```shell
92+
php artisan native:migrate:fresh
93+
```
94+
95+
#### Processes
96+
Make sure there are no lingering processes. Check your Activity Monitor/Task Manager to find stray processes from your
97+
app that may hang around after a build has failed, and force them to quit.
7198

7299
### 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
100+
Errors that occur in PHP execution during the application's boot-up sequence can cause the app to crash before it even
74101
starts.
75102

76103
A 500 error in your application code, for example, may prevent the main window from showing, but would leave the runtime's
@@ -80,18 +107,19 @@ Try booting your application in a standard browser to see if there are any error
80107
you're using Laravel Herd, for example, move your app development environment into your Herd root folder and go to
81108
`http://{your-app-folder-name}.test/` in your favorite browser.
82109

83-
Also make sure that the PHP version in the bundle is the same as the one you have installed on your machine
110+
Also make sure that the PHP version in the bundle is the same as the one you have installed on your machine, i.e.
111+
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
112+
current OS+arch.
84113

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:
114+
Checking this will also prove that the executable itself is stable:
87115

88116
#### For dev builds:
89117
M-series (ARM) Mac:
90118
```shell
91119
/path/to/your/app/vendor/nativephp/electron/resources/js/resources/php/php -v
92120
```
93121
Windows:
94-
```shell
122+
```
95123
C:\path\to\your\app\vendor\nativephp\electron\resources\js\resources\php\php.exe -v
96124
```
97125

@@ -102,6 +130,14 @@ M-series (ARM) Mac:
102130
```
103131

104132
Windows:
105-
```shell
133+
```
106134
C:\path\to\your\app\dist\win-unpacked\resources\app.asar.unpacked\resources\php\php.exe -v
107135
```
136+
137+
## Still stuck?
138+
If you've found a bug, please [open an issue](https://github.com/nativephp/laravel/issues/new) on GitHub.
139+
140+
There's also [Discussions](https://github.com/orgs/NativePHP/discussions) and
141+
[Discord](https://discord.gg/X62tWNStZK) for live chat.
142+
143+
Come join us! We want you to succeed.

0 commit comments

Comments
 (0)