1# Third-Party Dependency Management for Backend Delegates 2 3Disclaimer: We are planning to restructure the repository around delegates. 4With that some of these guidelines will change in the future. 5 6A delegate may depend on external, third-party libraries to efficiently 7implement ahead-of-time (AOT) `partition()` or `preprocess()` functions, and/or 8to implement runtime functions such as `init()` or `execute()`, or to run tests 9in a specific manner. This guide aims to classify different types of third-party 10dependencies a delegate might depend on, and provide a high level guidance on 11how to include them. 12 13## Ahead-of-Time Dependencies 14 15This includes dependencies used by the delegate's `partitioner()` and 16`preprocess()` functions to generate preprocessed result which 17will be used at later at runtime. 18 19Depending on how the `preprocess()` function is implemented this can be either 20Python 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* If the dependency is only needed by the files inside the 27 `executorch/backends/<delegate_name>/` directory, it should be introduced in a 28 way such that it is used only by the code under that directory. 29* The dependency should not be installed by default when installing 30 the ExecuTorch Python package. 31 32More details in the section [below](#python-dependencies). 33 34## Runtime Dependencies 35 36This category covers C++ dependencies used by the delegate runtime code. 37It can be as simple as a third-party math library to implement some 38delegate operator, or can be a whole framework handling the lowered 39subgraph for the delegate. 40 41**Guidelines:** 42 43At a high level, "only pay for what you use" should be the desired approach 44for these third-party dependencies. 45 46* Similar to the AOT dependencies, the use of this should also be restricted to 47 only the delegate runtime source files. 48* If a delegate has a dependency which is already part of 49 `executorch/third-party` then try to use that if possible. This 50 helps with reducing the binary size when the delegate is enabled. 51* The rest of the ExecuTorch code, outside of the delegate, should not depend on 52 this. And it should should build and run correctly without this dependency 53 when the delegate is disabled at build time. 54 55More details in the section [below](#runtime-dependencies). 56 57## Testing-Only Dependencies 58 59Some libraries or tools are only used for executing the delegate tests. These 60can either be a Python dependency or a C++ dependency depending on the type of 61the test. 62 63**Guidelines:** 64 65* For a Python test dependency, it should not be installed by default when 66 installing the ExecuTorch Python package. 67* For a C++ test dependency, it should not be part of the ExecuTorch runtime 68 even when the delegate is built/enabled. 69 70## Other Considerations 71 72### Versioning 73 74Explicit and specific is preferred. For example a PyPI version (or range) or 75a git tag/release. 76 77<!--- 78### End-User vs. Developer Experience 79 80TODO 81Need to add more about developer experiences, users selecting which delegates 82to enable/install for both AOT and Runtime 83---> 84 85### Documenting Dependencies 86At a minimum, some documentation under `executorch/backends/<delegate_name>/` 87should be provided when introducing a new dependency which includes, 88 89* Rationale for introducing a new third-party dependency 90* How to upgrade the dependency 91* Any special considerations for the new dependency 92 93*** 94 95After listing the high level guidelines, let's now talk about specific 96logistics to actually include a dependency for your delegate, 97 98## Python Dependencies 99 100Python packaging is complicated and continuously evolving. For delegate 101dependencies, we recommend that a delegate specifies its third-party 102dependencies under `executorch/backends/<delegate_name>/requirements.txt` to be 103supplied to pip at installation time. The goal is to decouple them from the core 104ExecuTorch dependencies. 105 106Version conflicts should be avoided by trying to use the dependency already 107included by ExecuTorch or by some other backend if possible. Otherwise try some 108other 109[recommended](https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts) 110ways to mitigate version conflicts. 111 112#### Local Python Packages 113If it is a git repository, it should be added as a git submodule. 114 115<!-- 116TODO: Add more details. Something like 117https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-from-vcs, 118but the URLs can't be in the requirements.txt, so not recommending this for now. 119--> 120 121## C++ Dependencies 122 123The recommended approach is to include a git submodule for a given C++ 124dependency in the `executorch/backends/<delegate_name>/third-party` directory. 125 126### CMake Support 127At a minimum CMake support is required. 128 129<!--- 130TODO: Add more details about: complying with ET runtime build configurations; 131standard switches for library linking (i.e. static, PIC), optimization flags 132pass through, etc. 133---> 134