1.. _native_posix:
2
3Native POSIX execution (native_posix)
4#######################################
5
6.. contents::
7   :depth: 1
8   :backlinks: entry
9   :local:
10
11Overview
12********
13
14.. warning::
15   ``native_posix`` is deprecated in favour of :ref:`native_sim<native_sim>`, and will be removed
16   in the 4.2 release.
17
18.. note::
19   For native_posix users, if needed, :ref:`native_sim<native_sim>` includes a compatibility mode
20   :kconfig:option:`CONFIG_NATIVE_SIM_NATIVE_POSIX_COMPAT`,
21   which will set its configuration to mimic a native_posix-like configuration.
22
23``native_posix`` is the predecessor of :ref:`native_sim<native_sim>`.
24Just like with :ref:`native_sim<native_sim>` you can build your Zephyr application
25with the Zephyr kernel, creating a normal Linux executable with your host tooling,
26and can debug and instrument it like any other Linux program.
27
28But unlike with :ref:`native_sim<native_sim>` you are limited to only using the host C library.
29:ref:`native_sim<native_sim>` supports all ``native_posix`` use cases.
30
31This board does not intend to simulate any particular HW, but it provides
32a few peripherals such as an Ethernet driver, display, UART, etc., to enable
33developing and testing application code which would require them.
34This board supports the same :ref:`peripherals<native_sim_peripherals>`
35:ref:`and backends as native_sim<native_sim_backends>`.
36
37.. _native_posix_deps:
38
39Host system dependencies
40************************
41
42Please check the
43:ref:`Posix Arch Dependencies<posix_arch_deps>`
44
45.. _native_important_limitations:
46
47Important limitations
48*********************
49
50This board inherits
51:ref:`the limitations of its architecture<posix_arch_limitations>`
52
53Moreover, being limited to build only with the host C library, it is not possible to build
54applications with the :ref:`Zephyr POSIX OS abstraction<posix_support>`, as there would be symbol
55collisions between the host OS and this abstraction layer.
56
57.. _native_posix_how_to_use:
58
59How to use it
60*************
61
62To build, simply specify the ``native_posix`` board as target:
63
64.. zephyr-app-commands::
65   :zephyr-app: samples/hello_world
66   :host-os: unix
67   :board: native_posix
68   :goals: build
69   :compact:
70
71Now you have a Linux executable, ``./build/zephyr/zephyr.exe``, you can use just like any
72other Linux program.
73
74You can run, debug, build it with sanitizers or with coverage just like with
75:ref:`native_sim<native_sim>`.
76Please check :ref:`native_sim's how to<native_sim_how_to_use>` for more info.
77
78.. _native_posix32_64:
79
8032 and 64bit versions
81*********************
82
83Just like :ref:`native_sim<native_sim>`, ``native_posix`` comes with two targets:
84A 32 bit and 64 bit version.
85The 32 bit version, ``native_posix``, is the default target, which will compile
86your code for the ILP32 ABI (i386 in a x86 or x86_64 system) where pointers
87and longs are 32 bits.
88This mimics the ABI of most embedded systems Zephyr targets,
89and is therefore normally best to test and debug your code, as some bugs are
90dependent on the size of pointers and longs.
91This target requires either a 64 bit system with multilib support installed or
92one with a 32bit userspace.
93
94The 64 bit version, ``native_posix/native/64``, compiles your code targeting the
95LP64 ABI (x86-64 in x86 systems), where pointers and longs are 64 bits.
96You can use this target if you cannot compile or run 32 bit binaries.
97