Skip to content

Commit

Permalink
Add troubleshooting section (#76)
Browse files Browse the repository at this point in the history
  • Loading branch information
ubruhin authored Nov 14, 2024
1 parent 072c1cd commit 524bf3c
Show file tree
Hide file tree
Showing 6 changed files with 161 additions and 0 deletions.
1 change: 1 addition & 0 deletions antora.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,5 @@ nav:
- modules/user-manual/nav.adoc
- modules/cli/nav.adoc
- modules/library-conventions/nav.adoc
- modules/troubleshooting/nav.adoc
- modules/development/nav.adoc
1 change: 1 addition & 0 deletions modules/ROOT/pages/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ bottom left of the page.
* xref:user-manual:index.adoc[User Manual]
* xref:cli:index.adoc[CLI Reference]
* xref:library-conventions:index.adoc[Library Conventions]
* xref:troubleshooting:index.adoc[Troubleshooting]
* xref:development:index.adoc[Development]
Didn't find what you're looking for?
Expand Down
3 changes: 3 additions & 0 deletions modules/troubleshooting/nav.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
* xref:index.adoc[]
** xref:logging.adoc[]
** xref:reporting.adoc[]
49 changes: 49 additions & 0 deletions modules/troubleshooting/pages/index.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
= Troubleshooting

In case you encounter any problems with LibrePCB, this chapter gives you some
tips to get them solved or to get help from the community.

== Workspace Sync (Dropbox, Cloud, Git, ...)

If you sync your LibrePCB workspace with a cloud or similar, it's important to
follow some rules to avoid problems:

* Exclude all files with pattern `cache_*` from the synchronization. These
files are stored in the workspace subdirectory `data/libraries/`. If
LibrePCB does not work correctly and you had these files synced, delete
those files manually (while LibrePCB is closed) and try again. These files
are automatically recreated after deletion.
* Consider excluding files named `.lock` from the synchronization too if you
experience problems with file locks. However, never open a project or
library at the same time from multiple computers!
* Hidden files ("dotfiles") must be synchronized. If hidden files are
ignored by the sync, LibrePCB will not work correctly.

Note that even when following these rules, it's still not guaranteed that
everything works correctly. Especially with clouds the problem is that they
are not operating "atomically", which can cause very serious troubles.
Therefore we do not recommend to store any LibrePCB files in a cloud.

Working with a version control system like Git however is fine, since it works
atomically and even allows to roll back a change in the very unlikely case
something is messed up. We just recommend to use version control per-project
and per-library, not for the whole workspace.

== Wayland

There are some known issues when using LibrePCB natively on Wayland. If you
experience any problems, please try XWayland or X11 (both should work fine).

== Slow/Laggy UI

On some systems, especially with large projects, the UI could get a bit
laggy. We are aware of this and try to improve it. In the mean time, try the
following things:

* Reduce grid density or disable grid completely
* Avoid huge schematics -- split them into multiple sheets (e.g. DIN A4 format)
* In the schematic editor, hide pin numbers (toggle menu:View[Show Pin Numbers])
* In the board editor, reduce the number of visible layers
* Enable or disable OpenGL in workspace settings (test both modes)
* If using a high-resolution display, try to reduce resolution
* On a laptop, plug in the charger :-)
64 changes: 64 additions & 0 deletions modules/troubleshooting/pages/logging.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
= Logging Output

For various kinds of problems, it helps to see what LibrePCB internally does
and what low-level errors occurred but aren't displayed (in every detail)
in the graphical user interface.

Those messages are always written to `stderr` -- To see them, just run LibrePCB
from a terminal. Note that on Windows you have to redirect `stderr` to a file
and open the file in Notepad afterwards.

.Windows cmd.exe (PowerShell doesn't work!)

[source,bash]
----
"C:\Program Files\LibrePCB\bin\librepcb.exe" > log.txt 2>&1
----

After closing LibrePCB, open `C:\Users\%USERNAME%\log.txt` in Notepad.

.MacOS Terminal

[source,bash]
----
/Applications/LibrePCB.app/Contents/MacOS/librepcb
----

.Linux/UNIX Shell

[source,bash]
----
/path/to/librepcb
----

Currently this is the only way to get logging messages. Logging to a file
is not implemented yet, and the verbosity cannot be configured.

.Example Output
[source,bash]
----
./librepcb-1.1.0-linux-x86_64-qt6.AppImage
[ INFO ] LibrePCB 1.1.0 (18a3d4589)
[ INFO ] Qt version: 6.6.2 (compiled against 6.6.2)
[ INFO ] Resources directory: "/tmp/.mount_librepHOglKc/opt/share/librepcb"
[ INFO ] Application settings: "/home/user/.config/LibrePCB/LibrePCB.ini"
[ INFO ] Cache directory: "/home/user/.cache/LibrePCB/LibrePCB"
[DEBUG-MSG] Network access manager thread started.
[DEBUG-MSG] Recently used workspace: "/home/user/LibrePCB-Workspace"
[DEBUG-MSG] Detected light theme based on window background color #efefef.
[DEBUG-MSG] Open workspace data directory "/home/user/LibrePCB-Workspace/data"...
[DEBUG-MSG] Load workspace settings...
[DEBUG-MSG] Successfully loaded workspace settings.
[DEBUG-MSG] Load workspace library database...
[DEBUG-MSG] Successfully loaded workspace library database.
[DEBUG-MSG] Successfully opened workspace.
[DEBUG-MSG] Workspace library scanner thread started.
[ INFO ] Loaded parts information cache from "/home/user/.cache/LibrePCB/LibrePCB/parts.lp".
[DEBUG-MSG] Cleaned outdated live information about 0 parts.
[DEBUG-MSG] Start workspace library scan in worker thread...
[DEBUG-MSG] Workspace libraries indexed: 47 libraries in 25 ms.
[DEBUG-MSG] Workspace library scan succeeded: 5515 elements in 12876 ms.
[DEBUG-MSG] Network access manager thread stopped.
[DEBUG-MSG] Workspace library scanner thread stopped.
[DEBUG-MSG] Exit application with code 0.
----
43 changes: 43 additions & 0 deletions modules/troubleshooting/pages/reporting.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
= Reporting Problems

If you like to report a problem or you want to ask for help, choose one of
the ways listed https://librepcb.org/help/[here].

Generally the discussion forum is always a good place to ask. A GitHub issue
is preferred for bug reports, but only if it's clearly a bug -- otherwise
ask in the forum first.

[IMPORTANT]
====
For any problem report, please include as much details as possible! Many
problems are platform-specific, deployment-specific, usecase-specific etc.
and we're all not clairvoyants so please let us know these details.
System Information::
If you are able to run LibrePCB, open the _About LibrePCB_ dialog and **copy
the whole text** from the _Details_ tab into your report. This is very
important information.
+
If you are not able to run LibrePCB, please let us know the following
information:
+
* Operating system & version
* CPU Architecture (x86, x86_64, ARM, Apple Silicon, ...)
* LibrePCB version (MAJOR.MINOR.PATCH)
* On Linux: X11 or Wayland?
Installation Method::
How did you install LibrePCB? Installer, Portable, Snap, Self-built, ...?
Steps to Reproduce::
What did you do before the problem occurred? Describe **exactly**,
step-by-step, what you did before the problem occurred.
Problem Description::
Describe **exactly** what happened. Which error messages occurred? How did
LibrePCB behave?
Logging Messages::
For technical problems, it can be helpful to also include all
xref:logging.adoc[logging messages].
====

0 comments on commit 524bf3c

Please sign in to comment.