Skip to content

Commit 5ac7661

Browse files
digantdesaifacebook-github-bot
authored andcommitted
3p dependency guideline (#272)
Summary: Pull Request resolved: #272 Provide a guideline for a delegate author to refer to when pulling in a 3p dependency. This is an early draft, and with many TBD items. Reviewed By: kimishpatel, cccclai Differential Revision: D49101948 fbshipit-source-id: 574e01abdcce24cb5f3e85be50978ac9665886a9
1 parent af370c2 commit 5ac7661

File tree

3 files changed

+211
-0
lines changed

3 files changed

+211
-0
lines changed

CONTRIBUTING.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,13 @@ must work with threading**
109109
common sources of binary bloat. Some use of templates is fine (e.g. an
110110
`ArrayRef<T>`, or code that handles multiple `ScalarType` types), but for the
111111
most part avoid them if possible.
112+
113+
## For Delegate Authors
114+
115+
### Dependencies Management for a Delegate
116+
117+
* Use [this](/docs/website/docs/contributors/delegates.md)
118+
guide when integrating your delegate with Executorch.
119+
120+
* Refer to [this](/docs/website/docs/contributors/delegates_and_dependencies.md)
121+
set of guidelines when including a 3p depenency for your delegate.
Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# How to integrate a Backend Delegate with Executorch?
2+
3+
Disclaimer: We are planning to restructure the repository around delegates.
4+
With that some of these guidelines will change in the future.
5+
6+
This is a high level guideline when integrating a backend delegate with Executorch.
7+
8+
## Directory Structure
9+
10+
Delegate files should be under this directory:
11+
`executorch/backends/<delegate_name>/`. Delegate name should be unique.
12+
13+
## Python files
14+
15+
Delegate Python files such as one implementing `preprocess()` or `partition()`
16+
functions for Executorch AoT flow, excluding any external third-party
17+
dependencies and their files, should be installed and available with
18+
the top level Executorch package. For third-party dependencies, please refer to
19+
[this](./delegates_and_dependencies.md).
20+
21+
## C++ sources
22+
23+
At a minimum, a delegate must provide CMake support for building its C++
24+
sources.
25+
26+
For the CMake setup, the delegate dir should be included by the
27+
top level `CMakeLists.txt` file using `add_subdirectory` CMake command, and
28+
should be built conditionally with an Executorch build flag like
29+
`EXECUTORCH_BUILD_<DELEGATE_NAME>`, see `EXECUTORCH_BUILD_XNNPACK` for example.
30+
For third-party dependencies, please refer to
31+
[this](./delegates_and_dependencies.md).
32+
33+
Adding buck2 support should make the delegate available to more
34+
Executorch users.
35+
36+
* More details TBD
37+
38+
<!---
39+
TODO
40+
Need to insert a CMake layer in `executorch/backends` to provide some
41+
uniform abstraction across delegates.
42+
--->
43+
44+
45+
## Tests
46+
47+
Tests should be added under `executorch/backends/<delegate_name>/test`.
48+
Tests can be either python or C++ tests, for adding more complex e2e please reach out to us.
49+
50+
* Python unit-tests, which are simple python tests to test AoT logic such as
51+
`partitioner()`, AoT export flow i.e., `nn.Module` to generating the `.pte` file.
52+
53+
* Runtime C++ tests, using gtest, can be implemented to test delegate `init()`
54+
or `execute()` logic.
55+
56+
## Documentation
57+
58+
A delegate must contain a `executorch/backends/<delegate_name>/README.md`
59+
explaining the basics of the delegate, directory structure, features, and known-issues if any.
60+
61+
Any extra setup step(s) beyond the ones listed above, should be documented in
62+
`executorch/backends/<delegate_name>/setup.md`
Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Dependencies Management for Backend Delegatation
2+
3+
Disclaimer: We are planning to restructure the repository around delegates.
4+
With that some of these guidelines will change in the future.
5+
6+
A delegate may depend on external, third-party libraries to efficiently
7+
implement ahead-of-time (AoT) `partition()` or `preprocess()` functions, and/or
8+
to implement runtime functions such as `init()` or `execute()`, or run tests in
9+
a specific manner. This guide aims to classify different types of third-party
10+
dependencies a delegate might depend on, and provide a high level guidance on
11+
how to include them.
12+
13+
## Ahead-of-Time Dependencies
14+
15+
This includes dependencies used by the delegate's `partitioner()` and
16+
`preprocess()` functions to generate preprocessed result which
17+
will be used at later at runtime.
18+
19+
Depending on how the `preprocess()` function is implemented this can be either
20+
Python or C++ dependency. This guide will talk about only Python AoT dependencies.
21+
22+
**Guidelines:**
23+
24+
* If Executorch already includes a dependency you require, prefer
25+
to use that if possible.
26+
* Since the dependency is only used by the files inside the
27+
`executorch/backends/<delegate_name>/` - it should introduced in
28+
a way that it is needed only by the code inside the backend delegate
29+
directory.
30+
* The dependency should not be installed by default when installing
31+
the Executorch Python package.
32+
33+
More details in the section [below](#python-dependencies).
34+
35+
## Runtime Dependencies
36+
37+
This category covers C++ dependencies used by the delegate runtime code.
38+
It can be as simple as a third-party math library to implement some
39+
delegate operator, or can be a whole framework handling the lowered
40+
subgraph for the delegate.
41+
42+
**Guidelines:**
43+
44+
At a high level, only pay for what you use should be the desired approach
45+
for these third-party dependencies.
46+
47+
* Similar to the AoT dependencies, the use of this should also be restricted to
48+
only the delegate runtime source files.
49+
* If a delegate has a dependency which is already part of
50+
`executorch/third-party` then try to use that if possible. This
51+
helps with reducing the binary size when the delegate is enabled.
52+
* Rest of the Executorch code, outside of the delegate, should not depend on
53+
this. And it should should build and run correctly without this dependency
54+
when the delegate is disabled at build time.
55+
56+
More details in the section [below](#runtime-dependencies).
57+
58+
## Testing-Only Dependencies
59+
60+
Some libraries, or tools are only used for executing the delegate tests. These
61+
can either be a Python dependency or a C++ dependency depending on the type of
62+
the test.
63+
64+
**Guidelines:**
65+
66+
* For a Python dependency, it should not be installed by default when
67+
installing the Executorch Python package.
68+
* If for C++ tests, it should not be part of the
69+
Executorch runtime even when the delegate is built/enabled.
70+
71+
## Other considerations
72+
73+
### Versioning
74+
75+
Explicit and specific is preferred. For example a pypi version (or a criteria) or
76+
a git tag/release.
77+
78+
### End user vs. Developer experience
79+
80+
* More details TBD
81+
82+
<!---
83+
TODO
84+
Need to add more about developer experiences, users selecting which delegates
85+
to enable/install for both AoT and Runtime
86+
--->
87+
88+
### Documenting the dependency
89+
At a minimum, some documentation under `executorch/backends/<delegate_name>/`
90+
should be provided when introducing a new dependency which includes,
91+
92+
* Rationale for introducing a new third-party dependency
93+
* How to upgrade the dependency
94+
* Any special considerations for the new dependency
95+
96+
***
97+
98+
After listing the high level guidelines, let's now talk about specific
99+
logistics to actually include a dependency for your delegate,
100+
101+
## Python Dependencies
102+
103+
Python packaging is complicated and continuously evolving. For delegate
104+
dependencies, we recommend that a delegate specifies its third-party
105+
dependencies under `executorch/backends/<delegate_name>/requirements.txt` to be
106+
supplied to pip at installation time. The goal is to decouple them from the core
107+
Executorch dependencies.
108+
109+
Version conflict should be avoided by trying to use the already included
110+
dependency by Executorch or by some other backend if possible. Otherwise
111+
try some other
112+
[recommended](https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts)
113+
ways to mitigate version conflicts.
114+
115+
#### Local Python Packages
116+
If it is a git repository, it should be added as a git submodule.
117+
118+
* More details TBD
119+
120+
<!-- Something like
121+
https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-from-vcs,
122+
but the URLs can't be in the requirements.txt, so not recommending this for now. -->
123+
124+
## C++ Dependencies
125+
126+
The recommended approach is to include a git submodule for a given C++
127+
dependency in the `executorch/backends/<delegate_name>/third-party`.
128+
129+
### buck2/CMake support
130+
At a minimum CMake support is required. Adding buck2 support should make
131+
the delegate available to more Executorch users.
132+
133+
* More details TBD
134+
135+
<!---
136+
TODO
137+
Complying with ET runtime build configurations. Standard switches for library
138+
linking (i.e. static, PIC), optimization flags pass through, etc.
139+
--->

0 commit comments

Comments
 (0)