doc: west: add tl;dr for moving to west and troubleshooting
These are based on user feedback on slack and the mailing list. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
This commit is contained in:
parent
bd4b24810a
commit
a09d3d69f9
3 changed files with 110 additions and 0 deletions
|
@ -34,6 +34,8 @@ context about the tool.
|
|||
:maxdepth: 1
|
||||
|
||||
install.rst
|
||||
moving-to-west.rst
|
||||
troubleshooting.rst
|
||||
repo-tool.rst
|
||||
manifest.rst
|
||||
config.rst
|
||||
|
|
57
doc/guides/west/moving-to-west.rst
Normal file
57
doc/guides/west/moving-to-west.rst
Normal file
|
@ -0,0 +1,57 @@
|
|||
.. _moving-to-west:
|
||||
|
||||
Moving to West
|
||||
##############
|
||||
|
||||
To convert a "pre-west" Zephyr setup on your computer to west, follow these
|
||||
steps. If you are starting from scratch, use the :ref:`getting_started`
|
||||
instead. See :ref:`west-troubleshooting` for advice on common issues.
|
||||
|
||||
#. Install west.
|
||||
|
||||
On Linux::
|
||||
|
||||
pip3 install --user -U west
|
||||
|
||||
On Windows and macOS::
|
||||
|
||||
pip3 install -U west
|
||||
|
||||
For details, see :ref:`west-install`.
|
||||
|
||||
#. Move your zephyr repository to a new :file:`zephyrproject` parent directory,
|
||||
and change directory there.
|
||||
|
||||
On Linux and macOS::
|
||||
|
||||
mkdir zephyrproject
|
||||
mv zephyr zephyrproject
|
||||
cd zephyrproject
|
||||
|
||||
On Windows ``cmd.exe``::
|
||||
|
||||
mkdir zephyrproject
|
||||
move zephyr zephyrproject
|
||||
chdir zephyrproject
|
||||
|
||||
The name :file:`zephyrproject` is recommended, but you can choose any name
|
||||
with no spaces anywhere in the path.
|
||||
|
||||
#. Create a :ref:`west installation <west-installation>` using the zephyr
|
||||
repository as a local manifest repository::
|
||||
|
||||
west init -l zephyr
|
||||
|
||||
This creates :file:`zephyrproject/.west`, marking the root of your
|
||||
installation, and does some other setup. It will not change the contents of
|
||||
the zephyr repository in any way.
|
||||
|
||||
#. Clone the rest of the repositories used by zephyr::
|
||||
|
||||
west update
|
||||
|
||||
**Make sure to run this command whenever you pull zephyr.** Otherwise, your
|
||||
local repositories will get out of sync. (Run ``west list`` for current
|
||||
information on these repositories.)
|
||||
|
||||
You are done: :file:`zephyrproject` is now set up to use west.
|
51
doc/guides/west/troubleshooting.rst
Normal file
51
doc/guides/west/troubleshooting.rst
Normal file
|
@ -0,0 +1,51 @@
|
|||
.. _west-troubleshooting:
|
||||
|
||||
Troubleshooting West
|
||||
####################
|
||||
|
||||
This page covers common issues with west and how to solve them.
|
||||
|
||||
"invalid choice: 'post-init'"
|
||||
*****************************
|
||||
|
||||
If you see this error when running ``west init``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west: error: argument <command>: invalid choice: 'post-init'
|
||||
(choose from 'init', 'update', 'list', 'manifest', 'diff',
|
||||
'status', 'forall', 'config', 'selfupdate', 'help')
|
||||
|
||||
Then you have an old version of west installed, and are trying to use it in an
|
||||
installation that requires a more recent version.
|
||||
|
||||
The easiest way to resolve this issue is to upgrade west and retry as follows:
|
||||
|
||||
#. Install the latest west with the ``-U`` option for ``pip3 install`` as shown
|
||||
in :ref:`west-install`.
|
||||
|
||||
#. Back up any contents of :file:`zephyrproject/.west/config` that you want to
|
||||
save. (If you don't have any configuration options set, it's safe to skip
|
||||
this step.)
|
||||
|
||||
#. Completely remove the :file:`zephyrproject/.west` directory (if you don't,
|
||||
you will get the "already in an installation" error message discussed next).
|
||||
|
||||
#. Run ``west init`` again.
|
||||
|
||||
"already in an installation"
|
||||
****************************
|
||||
|
||||
You may see this error when running ``west init``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
FATAL ERROR: already in an installation (<some directory>), aborting
|
||||
|
||||
If this is unexpected and you're really trying to create a new installation,
|
||||
then it's likely that west is using the :envvar:`ZEPHYR_BASE` :ref:`environment
|
||||
variable <env_vars>` to locate a west installation elsewhere on your system.
|
||||
This is intentional behavior; it allows you to put your Zephyr applications in
|
||||
any directory and still use west.
|
||||
|
||||
To resolve this issue, unset :envvar:`ZEPHYR_BASE` and try again.
|
Loading…
Add table
Add a link
Reference in a new issue