Skip to content

bbatsov/projectile

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

I am the maintainer of projectile for debian. (Aymeric Agon-Rambosson)

As part of the building process of our packages, we run the tests
provided by the upstream maintainers in a clean and empty
environment (no writable $HOME, no internet access, etc...). For
this reason, we sometimes uncover bugs that would remain masked on
the machines of the upstream maintainers, and of the users.

The test "projectile-parse-dirconfig-file" can break in a very
specific setting :

Since version 28.1, emacs has been shipped with
native-compilation, that is the possibility to compile elisp to
native instructions using libgccjit. Since elisp allows the
advising of functions implemented in C ("primitives"), it is
necessary to compile trampolines to replace those functions if we
want to advise them, in order to allow an arbitrary user-defined
function to be run instead.

The test library you use, buttercup, and more specifically its
function spy-on, advises functions routinely.

In the test we're interested in, buttercup (spy-on) changes the
definition of a few primitives in the offending test
(projectile-parse-dirconfig-file), namely file-exists-p,
file-truename and insert-file-contents.

The first one is advised so as to always return t, regardless of
whether the file is really present or not.

The first two are advised without error. The last one, however,
can fail because, being a primitive, a trampoline needs to be
compiled. We have the following backtrace in our build environment
:

comp-subr-trampoline-install(insert-file-contents)
comp-trampoline-search(insert-file-contents)
native-elisp-load("/tmp/buttercupKuLmvD/28.2-4001e2a9/subr--trampoline-696...
error: (native-lisp-load-failed "file does not exists"
"/tmp/buttercupKuLmvD/28.2-4001e2a9/subr--trampoline-696e736572742d66696c652d636f6e74656e7473_insert_file_contents_0.eln")

What happens here is the following : if we are in a situation
where the trampoline corresponding to the function
insert-file-contents is not already present in some eln-cache
directory on the machine, then the function comp-trampoline-search
should return nil, which would trigger the compilation of said
trampoline.

However, since comp-trampoline-search relies on file-exists-p, and
this last one has been advised so as to always answer yes,
comp-trampoline-search tries to load a file that does not exists,
hence our error.

You or your users probably never reach that state, probably
because you can always count on the trampoline being present
beforehand. But if it is not there, you should be able to
reproduce. We always reach that state because we run the tests in
a clean environment, where the trampoline is never present.

This error can be expected whenever a primitive is advised (in our
case insert-file-contents) while file-exists-p is already advised
so as to always return t, and the trampoline corresponding to the
primitive does not already exists on the file system.

There are two possible solutions : the first one is to try and
ensure the trampoline is present by the time of the advice, for
instance by compiling it unconditionally before the test. This is
not entirely reliable, as some environments could inhibit the
saving of this trampoline to the file system (this is what we do,
for instance).

The second one is to exclude the function insert-file-contents
(and indeed, any primitive you would want to advise while
file-exists-p is advised as to always return t) from trampoline
optimisation completely. The variable
native-comp-never-optimize-functions can be used to do just that.
This patch tweaks it accordingly.
e18ad4d

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
May 22, 2022 10:40
doc
November 22, 2022 22:33
August 20, 2020 10:11
November 23, 2022 10:18
February 5, 2020 16:05
August 20, 2020 10:11
November 22, 2022 22:32

Projectile

Build Status MELPA MELPA Stable NonGNU ELPA License GPL 3

Synopsis

Projectile is a project interaction library for Emacs. Its goal is to provide a nice set of features operating on a project level without introducing external dependencies (when feasible). For instance - finding project files has a portable implementation written in pure Emacs Lisp without the use of GNU find (but for performance sake an indexing mechanism backed by external commands exists as well).

Projectile tries to be practical - portability is great, but if some external tools could speed up some task substantially and the tools are available, Projectile will leverage them.

This library provides easy project management and navigation. The concept of a project is pretty basic - just a folder containing some special file (e.g. a VCS marker or a project descriptor file like pom.xml or Gemfile). Projectile will auto-detect pretty much every popular project type out of the box and you can easily extend it with additional project types.

Here are some of Projectile's features:

  • jump to a file in project
  • jump to a project buffer
  • jump to a test in project
  • toggle between files with same names but different extensions (e.g. .h <-> .c/.cpp, Gemfile <-> Gemfile.lock)
  • toggle between code and its test (e.g. main.service.js <-> main.service.spec.js)
  • jump to recently visited files in the project
  • switch between projects you have worked on
  • kill (close) all project buffers
  • grep (search) in project
  • replace in project
  • find references in project (using xref internally)
  • run shell commands in a project (e.g. make, lein)
  • support for multiple minibuffer completion/selection libraries (ido, ivy, helm and the default completion system)
  • automatic project discovery (see projectile-project-search-path)
  • integration with the built-in project.el library

There's also a rich ecosystem of third-party Projectile extensions that add even more features.


Patreon Paypal

I've been developing Projectile for over a decade now (since 2011). While it's a fun project to work on, it still requires a lot of time and energy to maintain.

You can support my work on Projectile via PayPal, Patreon and GitHub Sponsors.

Projectile in Action

Here's a glimpse of Projectile in action (using ivy):

Projectile Demo

In this short demo you can see:

  • finding files in a project
  • switching between implementation and test
  • switching between projects

Quickstart

The instructions that follow are meant to get you from zero to a running Projectile setup in a minute. Visit the online documentation for (way) more details.

Installation

package.el is the built-in package manager in Emacs.

Projectile is available on all major package.el community maintained repos - NonGNU ELPA, MELPA Stable and MELPA.

You can install Projectile with the following command:

M-x package-install [RET] projectile [RET]

Alternatively, users of Debian 9 or later or Ubuntu 16.04 or later may simply apt-get install elpa-projectile.

Finally add this to your Emacs config:

(projectile-mode +1)
;; Recommended keymap prefix on macOS
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
;; Recommended keymap prefix on Windows/Linux
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)

Those keymap prefixes are just a suggestion. Feel free to put there whatever works best for you.

Basic Usage

Enable projectile-mode, open a file in one of your projects and type a command such as C-c p f.

See the online documentation for more details.

To get the most of Projectile you also need to enable (and potentially install) some minibuffer completion framework (e.g. ido, ivy or selectrum). See this section of the documentation for more details.

Note: Historically projectile-completion-system defaulted to ido, but this was changed in version 2.3. You may need to enable ido-mode in your Emacs configuration if updating from an older version of Projectile.

Caveats

  • Some operations like search (grep) depend (presently) on external utilities such as find or fd (version 8.3.0+).
    • for older fd version add (setq projectile-generic-command "fd . -0 --type f --color=never") to your init-file
  • Commands depending on external utilities might misbehave on the fish shell.
  • Using Projectile over TRAMP might be slow in certain cases.
  • Some commands might misbehave on complex project setups (e.g. a git project with submodules).
  • Projectile was mostly tested on Unix OS-es (e.g. GNU/Linux and macOS), so some functionality might not work well on Windows.

Known issues

Check out the project's issue list a list of unresolved issues. By the way - feel free to fix any of them and send me a pull request. :-)

Contributors

Here's a list of all the people who have contributed to the development of Projectile (a.k.a. Projectile's Hall of Fame).

Joining this esteemed group of people is only a commit away!

Changelog

A fairly extensive changelog is available here.

License

Copyright © 2011-2022 Bozhidar Batsov and contributors.

Distributed under the GNU General Public License, version 3