================
@@ -0,0 +1,270 @@
+# Adding Target Support
+
+LLDB supports many combinations of architecture, operating system and other
+system components. In this document we describe the considerations and
+requirements for porting LLDB to a combination of those things. Which we will
+refer to as a "target" within this document.
+
+:::{note}
+The terms `Target` and `Platform` are used throughout LLDB, often
+referring to a subset of what this document calls a "target".
+Unfortunately there is no more specific word to use here.
+
+This document provides some hints on implementation, but because every target
+is unique, we expect developers to learn about implementation from existing
+targets.
+
+This document starts with the end of the process, proposing your taret for
+upstream inclusion. It is worth reading through this even if that is not one of
+your goals, as you will have to tackle the same topics even in a downstream
+implementation.
+
+## Upstreaming Proposal Process
+
+You must send an RFC to the LLDB Discourse forum before upstreaming
+new target support. This RFC must be accepted in some form by the community
+before any changes can be merged upstream that are specific to your target.
+
+This RFC follows the normal rules of the LLVM community decision making
process.
+
+We require an RFC for target support upstreaming because:
+* We want ensure there is some level of public discussion on the topic.
+ It is important that details, even those obvious to the community at the
time,
+ are written down so that future readers may learn from it.
+
+ :::{note}
+ Assuming they were done in good faith, these discussions are not to be used
+ to personally criticise anyone after the fact. Situations change, people make
+ mistakes, and that is ok.
+
+* These discussions forms the basis for future proposals and the assessment
+ of those proposals. Every proposal will be different in some way, and by
+ contrast with the past we can do the best job assessing them.
+
+RFCs are not required to be:
+* In a set format. Make a logical argument in whatever way you think fit.
+* Exhaustively detailed. Include what you think is relevant and the community
+ will ask for the rest.
+* Answering all the same questions, or making all the same points, as previous
+ proposals. Compare your target with existing targets, but not everything
will,
+ or has to, apply to yours.
+* A commitment to the maximum theoretical level of support (more on this
later).
+ If your resources are limited, say so, and that will be taken into account
+ (and vice versa, committing to a lot of work does not guarantee acceptance).
+
+## Expectations Of Upstream Code
+
+Listed below are some examples of factors considered when considering accepting
+code upstream. These are examples and RFC authors are free to add their own,
+leave some out, or explain why they do not apply to their proposal.
+
+If you do use these points, they need to come with an answer and evidence to
+justify the answer. Rather than simply "yes this applies to my target".
+In other words, your proposal must stand alone without requiring readers to
read this document as well.
+
+The first set cover your motivation for your being upstream rather
+than on a fork:
+
+* Will it help you distribute an LLDB that includes this target support?
+ For example if there is an existing community for this
+ target, and how would they acquire LLDB?
+* Will it enable a wider community than your own forks would?
+ For example for it to be included in Linux distribution packaging.
+* Will it improve support for other targets by being there?
+ For example if we already support Operating System X on Architecture Y,
+ adding Architecture Z support may improve both as a side effect.
+* Will it help you keep your changes in sync?
+ For example if it involves fundamental changes to LLDB, or you have a very
+ small amount of maintenance resources in your community.
+* What other costs (or benefits) do you incur staying on a fork?
+ For example, your company might already have a fork.
+
+The next set are about whether you, your community, or the LLDB community, can
+adequately maintain the code upstream:
+
+* Who will be the maintainers for this target? Ideally there will be more than
+ one, who is present in the LLVM community and can be contacted
+ in a few different ways.
+* How often will it be tested, where, by whom and who will pay for it?
+* Who will address problems with it? Will it always be the named maintainers,
+ is it so common that anyone in upstream LLDB can deal with it, or perhaps
+ only employees of a specific company will be required to work on it.
+* When it breaks how easy will it be for the upstream LLDB community to
continue
+ their work without disruption?
+* If upstream contributors want to reproduce issues on your target, how can
+ they access it? Can it be emulated or virtualized? Does it require them to
+ sign a license? Do you offer access for open source projects? (and does that
+ include employees of other companies)
+
----------------
JDevlieghere wrote:
The previous paragraph basically boils down to a cost/benefit analysis. I think
it's worth calling out that we're doing that analysis from the community
perspective and that that's motivated by the health of the community and the
project.
https://github.com/llvm/llvm-project/pull/207166
_______________________________________________
lldb-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
