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:
Marti Bolivar 2019-08-28 00:42:01 -06:00 committed by Carles Cufí
commit a09d3d69f9
3 changed files with 110 additions and 0 deletions

View file

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

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

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