blob: e8004a99b7fedf53682bcdc21931bd450b130802 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
= Troubleshooting
In case you run into issues here are a few tips that can help you diagnose the
problem.
Generally, it's not a bad idea to configure Emacs to spit the backtrace on error
(instead of just logging the error in the `+*Messages*+` buffer). You can toggle
this behavior by using kbd:[M-x] `toggle-debug-on-error`.
== Debugging Projectile commands
Emacs features a super powerful built-in
http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html[Emacs Lisp debugger]
and using it is the best way to diagnose problems of any kind.
TIP: Here's a https://www.youtube.com/watch?v=odkYXXYOxpo[great crash course] on
using the debugger.
To debug some command you need to do the following:
* Figure out the name of the command you want to debug (e.g. by using kbd:[C-h k]
to see which command is associated with some keybinding)
* Find the source of the command (e.g. by using kbd:[M-x] `find-function`
kbd:[RET] `function-name`)
* Press kbd:[C-u C-M-x] while in the body of the function
* Run the command again
At this point you'll be dropped in the debugger and you can step forward until
you find the problem.
== Profiling Projectile commands
Emacs comes with a https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html[built-in
profiler]. Using
it is pretty simple:
. Start it with kbd:[M-x] `profiler-start`.
. Invoke some commands.
. Get the report with kbd:[M-x] `profiler-report`.
TIP: If you intend to share the profiling results with someone it's a good idea to
save the report buffer to a file with kbd:[C-x C-w].
== Commonly encountered problems (and how to solve them)
=== Using some command causes Emacs to freeze for a while
Sometimes a Projectile command might hang for a while (e.g. due to a bug or a
configuration issue). Such problems are super annoying, but are relatively easy
to debug. Here are a few steps you can take in such situations:
* Do kbd:[M-x] `toggle-debug-on-quit`
* Reproduce the problem
* Hit kbd:[C-g] around 10 seconds into the hang
This will bring up a backtrace with the entire function stack, including
function arguments. So you should be able to figure out what's going on (or at
least what's being required).
=== Projectile recognizes the wrong project
If Projectile does not think you are in a project, check how you
expect Projectile to recognize the project: it needs the presence of
an indicator file like `.git` or similar at the project root. If the
directory you want to be a project is not version-controlled, a file
named `.projectile` will do.
Note that Projectile caches the operation of checking which project
(if any) a file belongs to. If you have already opened a file, then
later added a marker file like `.projectile`, run `M-x
projectile-invalidate-cache` to reset the cache.
=== I upgraded Projectile using `package.el` and nothing changed
Emacs doesn't load the new files, it only installs them on disk. To see the
effect of changes you have to restart Emacs.
=== Some commands not working properly with the fish shell
I'm not sure what's causing this (likely different quoting rules), but it's easy to fix it:
[source,elisp]
----
(setq shell-file-name "/bin/bash")
----
In general, I've noticed that Emacs doesn't play very well with fish.
|
