1.. _west-history:
2
3History and Motivation
4######################
5
6West was added to the Zephyr project to fulfill two fundamental requirements:
7
8* The ability to work with multiple Git repositories
9* The ability to provide an extensible and user-friendly command-line interface
10  for basic Zephyr workflows
11
12During the development of west, a set of :ref:`west-design-constraints` were
13identified to avoid the common pitfalls of tools of this kind.
14
15Requirements
16************
17
18Although the motivation behind splitting the Zephyr codebase into multiple
19repositories is outside of the scope of this page, the fundamental requirements,
20along with a clear justification of the choice not to use existing tools and
21instead develop a new one, do belong here.
22
23The basic requirements are:
24
25* **R1**: Keep externally maintained code in separately maintained repositories
26  outside of the main zephyr repository, without requiring users to manually
27  clone each of the external repositories
28* **R2**: Provide a tool that both Zephyr users and distributors can make use of
29  to benefit from and extend
30* **R3**: Allow users and downstream distributions to override or remove
31  repositories without having to make changes to the zephyr repository
32* **R4**: Support both continuous tracking and commit-based (bisectable) project
33  updating
34
35
36Rationale for a custom tool
37***************************
38
39Some of west's features are similar to those provided by
40`Git Submodules <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ and
41Google's `repo <https://gerrit.googlesource.com/git-repo/>`_.
42
43Existing tools were considered during west's initial design and development.
44None were found suitable for Zephyr's requirements. In particular, these were
45examined in detail:
46
47* Google repo
48
49  - Does not cleanly support using zephyr as the manifest repository (**R4**)
50  - Python 2 only
51  - Does not play well with Windows
52  - Assumes Gerrit is used for code review
53
54* Git submodules
55
56  - Does not fully support **R1**, since the externally maintained repositories
57    would still need to be inside the main zephyr Git tree
58  - Does not support **R3**, since downstream copies would need to either
59    delete or replace submodule definitions
60  - Does not support continuous tracking of the latest ``HEAD`` in external
61    repositories (**R4**)
62  - Requires hardcoding of the paths/locations of the external repositories
63
64Multiple Git Repositories
65*************************
66
67Zephyr intends to provide all required building blocks needed to deploy complex
68IoT applications. This in turn means that the Zephyr project is much more than
69an RTOS kernel, and is instead a collection of components that work together.
70In this context, there are a few reasons to work with multiple Git
71repositories in a standardized manner within the project:
72
73* Clean separation of Zephyr original code and imported projects and libraries
74* Avoidance of license incompatibilities between original and imported code
75* Reduction in size and scope of the core Zephyr codebase, with additional
76  repositories containing optional components instead of being imported
77  directly into the tree
78* Safety and security certifications
79* Enforcement of modularization of the components
80* Out-of-tree development based on subsets of the supported boards and SoCs
81
82See :ref:`west-basics` for information on how west workspaces manage multiple
83git repositories.
84
85.. _west-design-constraints:
86
87Design Constraints
88******************
89
90West is:
91
92- **Optional**: it is always *possible* to drop back to "raw"
93  command-line tools, i.e. use Zephyr without using west (although west itself
94  might need to be installed and accessible to the build system). It may not
95  always be *convenient* to do so, however. (If all of west's features
96  were already conveniently available, there would be no reason to
97  develop it.)
98
99- **Compatible with CMake**: building, flashing and debugging, and
100  emulator support will always remain compatible with direct use of
101  CMake.
102
103- **Cross-platform**: West is written in Python 3, and works on all
104  platforms supported by Zephyr.
105
106- **Usable as a Library**: whenever possible, west features are
107  implemented as libraries that can be used standalone in other
108  programs, along with separate command line interfaces that wrap
109  them.  West itself is a Python package named ``west``; its libraries
110  are implemented as subpackages.
111
112- **Conservative about features**: no features will be accepted without
113  strong and compelling motivation.
114
115- **Clearly specified**: West's behavior in cases where it wraps other
116  commands is clearly specified and documented. This enables
117  interoperability with third party tools, and means Zephyr developers
118  can always find out what is happening "under the hood" when using west.
119
120See :github:`Zephyr issue #6205 <6205>` and for more details and discussion.
121