@@ -10,10 +10,17 @@ you don’t need to declare these dependencies second time in `Eldev`
1010and keep track that they remain in sync.
1111
1212However, you do need to tell Eldev how to _find_ these dependencies.
13- Like Cask, by default it doesn’t use any package archives. To tell it
14- to use an archive, call function `eldev-use-package-archive` in
15- `Eldev` (you have such forms already in place if you have used `eldev
16- init`). For example:
13+ There are three ways of locating packages: <<package-archives ,using
14+ Elisp package archives >>, <<vc-repositories ,using VC (Git)
15+ repositories >> and <<local-sources,on your local file system>>.
16+
17+ [#package-archives]
18+ === From Elisp package archives
19+
20+ By default Eldev doesn’t use any package archives. To instruct it to
21+ use an archive to locate packages, call function
22+ `eldev-use-package-archive` in file `Eldev` (you have such forms
23+ already in place if you have used `eldev init` ). For example:
1724
1825[source]
1926----
@@ -62,39 +69,102 @@ they are installed first. However, if you want to check if package
6269archives have been specified correctly and all dependencies can be
6370looked up without problems, you can explicitly use command `prepare` .
6471
65- [#local-dependencies]
66- === Local dependencies
72+ [#vc-repositories]
73+ === From VC (Git) repositories
74+
75+ {since-1-11} If a package you depend on isn’t available from a package
76+ archive (e.g. MELPA), this is still not a problem as long as there is
77+ a Git repository for it. Simply add to file `Eldev` a form like this:
78+
79+ [source]
80+ ----
81+ (eldev-use-vc-repository 'dep-name :git "FULL-URL")
82+ ----
83+
84+ If the package is available on GitHub, you can avoid specifying the
85+ full URL by using the shortened form:
86+
87+ [source]
88+ ----
89+ (eldev-use-vc-repository 'dep-name :github "USER/REPOSITORY")
90+ ----
91+
92+ Now, whenever a package called `dep-name` is needed, Eldev will first
93+ fetch given Git repository, build an Elisp package from it and provide
94+ it to the standard Emacs package manager for use.
95+
96+ Like <<package-archives,with package archives>>, function
97+ `eldev-use-vc-repository` itself doesn’t describe _how_ you intend to
98+ use given package. It merely tells Eldev where to find it. Only if
99+ the package is listed as a <<dependencies,regular dependency>> of your
100+ project or you register it as <<additional-dependencies ,an additional
101+ dependency >>, will the repository actually get fetched.
102+
103+ If the project fetched from a repository doesn’t use Eldev itself, the
104+ tool might have problems building a package from it. In this case you
105+ can pass a <<setup-procedure,setup form>> to it:
106+
107+ [source]
108+ ----
109+ (eldev-use-vc-repository ... :setup FORM)
110+ ----
111+
112+ This form will be given to child Eldev processes whenever a package
113+ needs to be created out of the VC-fetched project. Most likely you
114+ will need to tell child Eldev how to locate dependencies of _that_
115+ project. The best way to figure it out is to check out the repository
116+ and create file `Eldev` in it with required contents
117+ (<<initializing,`eldev init`>> might help). Instead of committing the
118+ created file, convert its contents into an Elisp form (use `progn` if
119+ needed) and pass it as a value of `:setup` in your _main_ project.
120+
121+ By default, Eldev will check out the repository at the latest stable
122+ tagged release. If there are none, however, it will just use the HEAD
123+ commit. Eldev respects the options `--stable` /`--unstable` described
124+ in the previous section also for VC repositories. For example, the
125+ latter makes it ignore the releases and always use the latest commit.
126+ Finally, if you _always_ want to build from a specific commit, e.g. to
127+ make build process more stable, you can pass optional argument
128+ `:commit` to `eldev-use-vc-repository` . Its value must be a string:
129+ either a tag name or a _full_ (not shortened) Git commit hash.
130+
131+ [#local-sources]
132+ === From your file system (local sources)
67133
68134Imagine you are developing more than one project at once and they
69135depend on each other. You’d typically want to test the changes you
70136make in one of them from another right away. If you are familiar with
71137Cask, this is solved by linking projects in it.
72138
73139Eldev provides a more flexible approach to this problem called _local
74- dependencies_ . Let’s assume you develop project `foo` in directory
75- `~/foo` and also a library called `barlib` in `~/barlib` . And `foo`
76- uses the library. To have Eldev use your local copy of `barlib`
77- instead of downloading it e.g. from MELPA, add the following form in
78- file `~/foo/Eldev-local` :
140+ sources_ . Let’s assume you develop project `foo` in directory `~/foo`
141+ and also a library called `barlib` in `~/barlib` . And `foo` uses the
142+ library. To have Eldev use your local copy of `barlib` instead of
143+ downloading it e.g. from MELPA, add the following form in file
144+ `~/foo/Eldev-local` :
79145
80146[source]
81147----
82- (eldev-use-local-dependency "~/barlib")
148+ (eldev-use-local-sources "~/barlib")
83149----
84150
151+ NOTE: Before 1.11 the function was named `eldev-use-local-dependency` .
152+ This name is still available for backward compatibility.
153+
85154Note that the form _must not_ be added to `Eldev` : other developers
86155who check out your project probably don’t even have a local copy of
87156`barlib` or maybe have it in some other place. In other words, this
88157should really remain your own private setting and go to `Eldev-local` .
89158
90- Local dependencies have _loading modes_ , just as the project’s package
159+ Local sources have _loading modes_ , just as the project’s package
91160itself. Those will be discussed <<loading-modes,later>>.
92161
93- Eldev correctly handles situations with changing definitions of local
94- dependencies. I.e. by simply commenting out or uncommenting
95- `eldev-use-local-dependency` call, you can quickly test your project
96- both with a MELPA-provided package and with a local dependency — Eldev
97- will adapt without any additional work from you.
162+ Eldev correctly handles situations with adding, removing or otherwise
163+ changing local source definitions. I.e. by simply commenting out or
164+ uncommenting `eldev-use-local-sources` call, you can quickly test your
165+ project both with a MELPA-provided package and with local (and
166+ presumably just changed) copy of its dependency sources — Eldev will
167+ adapt without any additional work from you.
98168
99169[#additional-dependencies]
100170=== Additional dependencies
0 commit comments