|
| 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