Differences

This shows you the differences between two versions of the page.

--- docs:guide-developer:overview [2018/09/25 02:28] – Change references of LEDE to OpenWrt chittti
+++ docs:guide-developer:overview [2022/01/19 14:02] (current) – sorcun
@@ Line 1: / Line 1: @@
-=====Overview =====
+====== Overview ======
-If you are already familiar with Linux systems, you will find your way pretty easily, if you are not, then we will need to start from basic concepts first.
+If you are already familiar with GNU/Linux systems, you will find your way pretty easily, if you are not, we will need to start from basic concepts first.
-You might have read that OpenWrt is a Linux distribution (or "distro") aimed at embedded devices.\\ A Linux "**distribution**" is a project that creates and maintains packages used to create a linux operating system tailored to the user's needs.\\ A "**package**" is a compressed archive containing a program or some scripts, its accompanying configuration files and also the information used to integrate it in the operating system. These packages are handled by a **package manager**, (opkg in OpenWrt) a program that downloads/opens/installs/uninstalls the packages.\\
+You might have read that OpenWrt is a **GNU/Linux distribution** (or "distro") aimed at embedded devices.\\
-So, a OpenWrt firmware is made by assembling packages around a Linux kernel.
+A GNU/Linux **distribution** is a project that creates and maintains //packages//, used with a Linux kernel to create a GNU/Linux operating system tailored to users' needs.\\
+A **package** is a compressed archive containing a program, a [[wp>Library_(computing)|library]] or some scripts, its accompanying configuration files and also information used to integrate it in the operating system. These packages are handled by a **package manager** (opkg in OpenWrt); a program that downloads/opens/installs/uninstalls the packages.\\
+So, an OpenWrt firmware is made by assembling packages around a Linux kernel.
-Each package is compiled separately and then when it's all done the needed packages are "installed" in a temporary folder that will then be
+Each package is compiled separately, and when all are done the needed packages are "installed" in a temporary directory that will then be the compressed-read-only [[wp>SquashFS]] partition in the device firmware.
-compressed to become the compressed-read-only partition (squashfs) in the device firmware.
-Also the kernel is handled like a package, but is added to the firmware image in the special way each device's bootloader expects it, so you can replace the stock firmware without touching the bootloader itself (that is dangerous and not always possible).
+While the kernel is handled as a package, it is added to firmware images in the special way each device's bootloader expects. So you can replace the stock firmware without touching the bootloader (that is dangerous and not always possible).
-The last step in the building process is actually creating a firmware file, (the files you use to install OpenWrt or to upgrade it).\\
+The last step in the building process is actually creating a firmware file, the file to install or upgrade OpenWrt.\\
-This file is usually a disk image ready to be written raw in the internal flash storage of the device, so you will find many developers that just call it "image" on IRC or in the mailing list.
+This file is usually a memory image ready to be written as is on the internal flash storage of the device. You may realise many developers who just call it "image" on IRC or in the mailing list.
-====How a package is compiled===
+===== How a package is compiled =====
-If you look at a package Makefile (the file defining settings for building a specific package), https://github.com/openwrt/openwrt/blob/master/package/utils/busybox/Makefile you will notice that it states the official download link for the sources that will be compiled, a SHA256 hash to check the integrity of such download, and two version numbers (one for upstream and one for OpenWrt).
+If you look at a package's **Makefile**((the file defines settings for building the package, [[https://github.com/openwrt/openwrt/blob/master/package/utils/busybox/Makefile|e.g. busybox's]])), you will notice it states the official download link for the sources to be compiled, a SHA256 hash to check the integrity of such download, a version number of the upstream project as package base and a release number to indicate OpenWrt changes.
-On some other packages it will state git commit/timestamp or other way to identify the same source to pull down and build.
+On some packages the version number states git commit, timestamp or another expression to identify the source code version to pull down and build.
 They generally favor archives with sources from official releases, but some upstream projects don't always have that.
-In /patches folder of each package's folder you will find any patches that will be applied to the source after downloading it, before
+In **patches** directory of each package you will find any patches that will be applied to the source after downloading and before compiling it: (e.g. [[https://github.com/openwrt/openwrt/tree/master/package/utils/busybox/patches|pathches dir of busybox]]).
-compiling it:
+There are also other directories for configuration files or uci integration.
-https://github.com/openwrt/openwrt/tree/master/package/utils/busybox/patches
-There are also other folders for configuration files or for uci integration (not always present).
-The kernel's makefile is a bit more complex because of reasons, but you can see that it still uses the same structure, pulling down the same kernel version (depending from device) every time.
+The kernel's Makefile is a bit more complex, but you can see that it still uses the same structure for pulling down the same kernel version depending on device every time. e.g. [[https://github.com/openwrt/openwrt/blob/master/package/kernel/linux/Makefile|Linux Makefile]]
-https://github.com/openwrt/openwrt/blob/master/package/kernel/linux/Makefile
-All packages are compiled by OpenWrt's own toolchain, which is again handled like packages (see /toolchain and /tools in the source) so you will always have the same compiler/tools as everyone else as they get downloaded from the same sources at the same version.
+All packages are compiled by OpenWrt's own toolchain, which is again handled like packages (see /toolchain and /tools in the source), so you will always have the same compilers/tools as everyone else as they get downloaded from the same sources at the same version.
-When you run a **make** the OpenWrt build system will use your system's existing building infrastructure to compile the OpenWrt's toolchain first,
+When you run ''make'' the OpenWrt build system will use your system's existing building infrastructure to compile the OpenWrt's toolchain first, and then use that to compile the packages. This also has the major benefit of not requiring the user to set up a cross-compiling toolchain that is rather annoying and relatively complex.
-and then use that to compile the packages. This also has the major benefit of not requiring the user to set up a cross-compiling toolchain
-that is rather annoying and relatively complex.
-====Package feeds====
+===== Package feeds =====
 Not all packages you can install in OpenWrt are from OpenWrt project proper, in fact most packages are not.
-The packages from OpenWrt's main repository are maintained directly by core developers (and they are the more important or even essential components of OpenWrt firmware, or parts of the build system), and "**package feeds**" that are source repositories that contain additional packages, maintained by the community (each package has its own maintainer).
+The packages from OpenWrt's main repository are maintained directly by core developers, and they are the important, even essential components of OpenWrt firmware or parts of the build system. "**package feeds**" are source repositories that contain additional packages maintained by the community, and each package has its own maintainer.
-This is OpenWrt's main repo (on github) https://github.com/openwrt/openwrt
+This is OpenWrt's main repo on github: [[https://github.com/openwrt/openwrt]]
 These are official package feeds:
-https://github.com/openwrt/luci
+  * [[https://github.com/openwrt/luci]]
-https://github.com/openwrt/telephony
+  * [[https://github.com/openwrt/telephony]]
-https://github.com/openwrt-routing/packages
+  * [[https://github.com/openwrt-routing/packages]]
-https://github.com/openwrt/packages
+  * [[https://github.com/openwrt/packages]]
 Being "official feeds", the packages therein will be compiled and offered by the official download server, but they are not technically OpenWrt proper, they are community-maintained.
-The "package feed" system is designed to allow easy addition of your own custom feeds too in your custom firmware images, but you will have to compile them and host them on your own servers, of course.
+The "package feed" system is designed to allow easy addition of your own custom feeds to your own custom firmware images, but of course you will have to compile them and host them on your own servers.
-If you look at the built packages here on the download server (this is the same server opkg uses to download packages in a live OpenWrt system), https://downloads.openwrt.org/releases/18.06.1/packages/x86_64/
-They are divided by feed name, packages in "base" come from main repository, and also from main repository you get packages that are found in target-specific folders, like for example here https://downloads.openwrt.org/releases/18.06.1/packages/x86_64/packages/ that you see has mostly kmod-* and other drivers.
-====Package Versions====
-As said above, package makefiles have PKG_VERSION that shows the upstream version (major version) and PKG_RELEASE that is used to show changes on the OpenWrt side (the minor version). If you see a package that lists version as 123-1, it's major version is 123 and it's minor version is 1.
-Packages with a timestamp use that instead of major version, and they still have a minor version, for example  2016-09-21-42ad5367-1 where the last "1" is the minor version.
-You can see all versions used in the first page of the table of packages in the wiki https://openwrt.org/packages/start
-Or by browsing a Package.manifest in the package download folders https://downloads.openwrt.org/releases/18.06.1/packages/mips_24kc/base/Packages.manifest
+If you look at the built packages [[https://downloads.openwrt.org/releases/21.02.1/packages/x86_64/|here]] on the download server (this is the same server opkg uses to download packages in a live OpenWrt system), they are divided by feed name, packages in "base" come from main repository, and also from main repository you get packages that are found in target-specific directories, like for example [[https://downloads.openwrt.org/releases/21.02.1/packages/x86_64/packages/|here]] what you see is mostly drivers like kmod-*.
-====Repeatable builds====
+===== Package versions =====
-Most of the above system allows repeatable builds, the hashes and time stamps of source archives or commits are written in
+As said above, package Makefiles have PKG_VERSION tag that shows the upstream version which is the major version of the package, and PKG_RELEASE tag that is used to show changes on the OpenWrt side, that is the minor version. If you see a package that lists version as 123-1, its major version is 123 and minor version is 1.
-the package's makefile in the git repository (either main repo or community package feeds), you can see full history of changes to that file with git.
-There is a cache server that stores source archives because it's more convenient than having the build bots spamming upstream download servers
+Some packages have timestamp or git commit as major version, for example  2016-09-21-42ad5367-1 where the last "1" is the minor version.
-and it is a fallback if the upstream download disappears, it should keep the source packages for a long while (as long as the release is supported for sure, as it is used by build bots).
-It is here http://sources.lede-project.org/
+You can see all versions used in the first page of the [[packages:table:start|table of packages]].
-Also OpenWRT's source cache server is used https://downloads.openwrt.org/sources/
+Or by browsing a Package.manifest in the package download directory [[https://downloads.openwrt.org/releases/21.02.1/packages/mips_24kc/base/Packages.manifest]]
+===== Repeatable builds =====
+Aforementioned system allows repeatable builds. The major version of source archives are written in the packages' Makefiles in the git repositories of main and community package feeds; you can see full history of changes to that file with //git//.
+There is a cache server that stores source archives because it's more convenient than having the build bots spamming upstream download servers, and it also is a fallback if the upstream server disappears. It should keep the packages' sources for a long while, as they are used by build bots as long as the releases depend on them are supported for sure.
+It is here [[https://sources.openwrt.org/]]