diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..3145cde --- /dev/null +++ b/.travis.yml @@ -0,0 +1,31 @@ +language: generic + +services: +- docker + +before_install: +- docker pull hvarga/latex-docker + +script: +- docker run --rm -v ${PWD}:/home/latex/work -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --user root --entrypoint make hvarga/latex-docker + +before_deploy: +- git tag "build-$TRAVIS_BUILD_NUMBER" + +deploy: + provider: releases + api_key: + secure: mLUzVIQpVAMybaHzUkjt33CC1HAnOxqCDYDmaW/0XHmOWHgNqxDqmotTDNZIFijxo/kS1dtDEaTdcUp4d4TML7AKdnk7USXwXYQFYWKTqmWo0cjd4lRIj7f2HVfthkxuhdjN8uSz7tLO8R4kM1iJwMF08ph8FMnjvelCNOxwPWQyYLUTVCgTsEfV7ApTJyMpbLZVeF2R4WlX0sofin+ggYN6++BBsXWR15pRjWxDls7BVkoRodtHR5Kf/QqFbHFXQ1WUqsgqEsrkXLE1klxG/a1Rio3hzByMElglA1tZUoq7L26Hz2lJ29PzugW3pwErsuz4N9MSiCDov3xa/hTY35V5uAItleTutp3qQlI4r+NGM6ydkpiRjR+ulxhljlmEYrg65nZZYIdrVTirsS92Duhis0R2rTp0fYXC6bmRF4fb0qVy3Ms+vBPIhogZkJfuyscp4SAqB8OcWqy0CY7w+KSGD89Bf0uBKE4BvrXwJ/sIVPvNLhFETQs24B6QEbiLnUkVnTVBRpoH3/zuqGnKkm3sOKOUHn/G45C1SMWpRgvEPBUPUMUwuqudA6+Zri9X5cyvXu3/37yTxbytu/gHUBV3faIeiF6tA+lO2xNEjiZ5eAuXZefIUXfmJR0LQ6O0ZKWp0uuOIM///RCIMPPAKMGggJrJBRaGfCW0dFUy5xk= + file: + - presentation/build/openwrt-application-development-beamer.pdf + - presentation/build/openwrt-application-development-slides.pdf + - presentation/build/openwrt-application-development-handout.pdf + overwrite: true + skip_cleanup: true + on: + branch: master + tags: false + +branches: + except: + - /build-[0-9]/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1f089b9 --- /dev/null +++ b/LICENSE @@ -0,0 +1 @@ +This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..bdb2881 --- /dev/null +++ b/Makefile @@ -0,0 +1,4 @@ +all: + (cd presentation; make) +clean: + (cd presentation; make clean) diff --git a/README.md b/README.md new file mode 100644 index 0000000..6c8a94f --- /dev/null +++ b/README.md @@ -0,0 +1,105 @@ +# OpenWrt - Application Development + +[![Build Status](https://travis-ci.org/hvarga/openwrt-application-development.svg?branch=master)](https://travis-ci.org/hvarga/openwrt-application-development) + +The goal of this project is to write a presentation which will help you to learn the basic knowledge about the OpenWrt and its ecosystem so that you can create your own custom application which will run on OpenWrt. + +Presentation itself is written using LaTeX. + +## How to Generate a PDF + +To be able to generate a PDF yourself you have to have quite a large collection of tools. It is highly recommended to use prepared Docker Image. This Docker Image contains everything you need to start working on the presentation. Alternative is to manually install the LaTeX system like TeX Live yourself which is out of scope of this documentation. Follow the sections below to configure your environment using prepared Docker Image. + +### Docker Image + +There is a Docker Image already prepared for you. You need to have a Docker installed before using prepared Docker Image. + +After the Docker is installed, execute following command to get the prepared Docker Image: + +```plain +docker pull hvarga/latex-docker +``` + +And that's it. You can proceed to chapter [Download the Source Materials](#download-the-source-materials). + +For more information about the prepared Docker Image, read the https://github.com/hvarga/latex-docker. + +### Download the Source Materials + +Second step is to download the source materials for the presentation. This can be accomplished using the Git to clone the repository. You need to have Git installed on your system. So, one more tool to install. + +Use your system package manager to install Git or go to http://git-scm.com/downloads and choose your operating system and follow directions. + +Now that you installed the Git, it is time to clone the repository. + +Open up your terminal and enter the following: + +```plain +git clone git@github.com:hvarga/openwrt-application-development.git +``` + +Git will do its magic and you will have the source materials. + +### Generate PDF + +Position yourself in the root folder of cloned repository and execute following command: + +```plain +docker run --rm -v ${PWD}:/home/latex/work -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --entrypoint make hvarga/latex-docker +``` + +You don't have Docker or this Docker Image? Follow [Docker Image](#docker-image) chapter. + +Above command will start the Docker Container out of the Docker Image that you pulled earlier in [Docker Image](#docker-image) chapter. Docker Container will execute `make` and `make` will call `latexmk` which will take care of generating the PDF document. PDF will be stored in the `build/openwrt-application-development.pdf`. Enjoy reading! + +## How to Contribute to the Presentation + +Since this presentation is under the Creative Commons license, everyone is free to share and adapt it. + +So, if you are willing to contribute by correcting grammar mistakes, making structural changes, alter the visual appearance for better readability, supplement some sections or chapters with additional information's that can help out a reader or even writing a new sections or chapters than by any means - contribute. + +### Learn LaTeX + +This presentation is written using the [LaTeX](http://latex-project.org/). So, if you want to contribute to the presentation than, obviously, you need to know LaTeX. Its homepage has a lot of good information's for reading. But if I have to single out just one good book to read, than I would recommend ["The (Not So) Short Introduction to LaTeX2e"](http://ctan.tug.org/tex-archive/info/lshort/english/lshort.pdf). If you don't have the time to invest in learning another technology or you are just too lazy than, please, at least read this recommended book. + +### Configure Environment + +Now to the fun part - in order to contribute, first, follow the [How to Generate a PDF](#generate-pdf) section of this document. Note that if you want to contribute to the presentation than you need to have the Git. Without it, you cannot send me your changes that you made to the presentation. + +Contributions to this presentation will be handled by the Git and the GitHub. So, [create an account](https://github.com/join) on the GitHub if you don't have one already. You will use Git to make versions of your changes and the GitHub [pull requests](https://help.github.com/articles/using-pull-requests) to send me your changes. + +Please, read a bit about the [Git](http://git-scm.com/doc) and the [GitHub](https://help.github.com/) itself before you start with your contributions. + +### Use LaTeX and Vector Drawing Editor + +Docker Image that you pulled earlier in [Docker Image](#docker-image) chapter, besides generating PDF, also comes with a LaTeX editor called [TeXstudio](https://www.texstudio.org/) and vector drawing editor called [Ipe](http://ipe.otfried.org/). + +#### TeXstudio + +To run TeXstudio, execute following command in the root folder of cloned repository: + +```plain +docker run --rm -v ${PWD}:/home/latex/work -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix hvarga/latex-docker --ini-file /home/latex/profile.txsprofile +``` + +If you are experiencing problems with running above command, please read the https://github.com/hvarga/latex-docker. + +After TeXstudio loads, you need to open the `main.tex` file. Presentation root is located in `/home/latex/work` and the `main.tex` is available at `/home/latex/work/presentation/main.tex`. + +`main.tex` is the root document of the project since it contains `\begin{document}` statement. + +#### Ipe + +To run Ipe, execute following command in the root folder of cloned repository: + +```plain +docker run --rm -v ${PWD}:/home/latex/work -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --entrypoint ipe hvarga/latex-docker +``` + +Ipe saves drawings in PDF files which can then be directly included by LaTeX. Ipe also allows you to reopen your existing PDF made by Ipe. Besides this, it has a nice features like object snapping, grouping and aligning. Basic geometry primitives like lines, splines, polygons, circles etc. + +Happy contributing! + +## License + +Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License. diff --git a/presentation/Makefile b/presentation/Makefile new file mode 100644 index 0000000..83bbbdc --- /dev/null +++ b/presentation/Makefile @@ -0,0 +1,19 @@ +.PHONY: all pdf clean + +all: clean pdf + +pdf: + git log -1 --format=\\newcommand{\\commitid}{%H} > current_commit.tex + git log -1 --date=iso --format=\\newcommand{\\commitdate}{%ad} >> current_commit.tex + + latexmk -pdf -silent -time -pdflatex="pdflatex -interaction=nonstopmode -synctex=1" -use-make -aux-directory=build --output-directory=build main.beamer.tex + cp build/main.beamer.pdf build/openwrt-application-development-beamer.pdf + + latexmk -pdf -silent -time -pdflatex="pdflatex -interaction=nonstopmode -synctex=1" -use-make -aux-directory=build --output-directory=build main.slides.tex + cp build/main.slides.pdf build/openwrt-application-development-slides.pdf + + latexmk -pdf -silent -time -pdflatex="pdflatex -interaction=nonstopmode -synctex=1" -use-make -aux-directory=build --output-directory=build main.handout.tex + cp build/main.handout.pdf build/openwrt-application-development-handout.pdf +clean: + rm -rf build + rm -f current_commit.tex diff --git a/presentation/about.tex b/presentation/about.tex new file mode 100644 index 0000000..a5365c7 --- /dev/null +++ b/presentation/about.tex @@ -0,0 +1,79 @@ +\section*{About} + +\subsection*{License} +\begin{frame}{License} + \begin{center} + Presentation is written using \LaTeX. Source code is available at \href{https://github.com/hvarga/openwrt-application-development}{GitHub}. + \end{center} + \vfill + \begin{center} + \doclicenseImage + \\ + \doclicenseLongText + \end{center} +\end{frame} + + +\subsection*{Author} +\begin{frame}{Author} + \pause + \begin{itemize}[<+-|alert@+>] + \item Currently employed at \href{http://www.sartura.hr/}{Sartura} on developing tools and systems based on GNU/Linux distribution. + \item Day-to-day assignments include developing programmatic solutions, their integration, testing and documentation. + \item Oriented on a software development using C and Go programming languages. + \item Always open to the possibility of using new open source systems and tools. + \item Advocator of \textit{Open Source} philosophy. + \item Contributor to various open source projects like LLVM, GDB, OpenWrt, MUSL, Sysrepo... + \item \href{https://www.opensource-osijek.org}{Open Source Osijek} co-founder. + \end{itemize} +\end{frame} + +\subsection*{Contact} +\begin{frame}{Contact} + \begin{table} + \begin{tabular}{c l} + \huge \faGithub & \huge \href{https://github.com/hvarga}{hvarga} \\ + \huge \faLinkedin & \huge \href{https://linkedin.com/in/hvarga}{/in/hvarga} \\ + \huge \faEnvelope & \huge \href{mailto:hrvoje.varga@gmail.com}{hrvoje.varga@gmail.com} + \end{tabular} + \end{table} +\end{frame} + +\subsection*{Goal} +\begin{frame}{Goal} + \textbf{Cover the OpenWrt from the application development perspective}. + \pause + \begin{itemize}[<+-|alert@+>] + \item OpenWrt Basics. + \item OpenWrt Modules. + \item Custom Application. + \end{itemize} +\end{frame} + +\subsection*{Requirements} +\begin{frame}{Requirements} + \pause + \begin{itemize}[<+-|alert@+>] + \item Access to the Internet. + \item Basic understanding of a GNU/Linux operating system~\cite{starch-how_linux_works}~\cite{starch-linux_command_line}. + \item Basic understanding of the C programming language~\cite{prentice-c_programming_language}~\cite{wesley-c_primer_plus}~\cite{oreilly-understanding_and_using_c_pointers}. + \item Basic understanding of the GNU make system~\cite{oreilly-managing_projects_with_gnu_make}. + \item Basic understanding of Docker containerization system~\cite{turnbull-the_docker_book}. + \item Basic understanding of Git versioning control~\cite{torvalds-git}~\cite{chacon-pro_git}. + \item Your target device should already be supported by the OpenWrt. + \item Good sense of principles, patterns, designs and methods in software engineering. + \end{itemize} +\end{frame} + +\subsection*{Agenda} +\begin{withoutheadline} + \begin{frame}[allowframebreaks]{Agenda} + \textbf{Part I} + \tableofcontents[part=1, subsubsectionstyle=hide] + + \framebreak + + \textbf{Part II} + \tableofcontents[part=2, subsubsectionstyle=hide] + \end{frame} +\end{withoutheadline} diff --git a/presentation/bibliography.tex b/presentation/bibliography.tex new file mode 100644 index 0000000..85c387d --- /dev/null +++ b/presentation/bibliography.tex @@ -0,0 +1,6 @@ +\section*{References} + +\subsection*{Bibliography} +\begin{frame}[allowframebreaks]{Bibliography} + \printbibliography[heading=none] +\end{frame} diff --git a/presentation/main.beamer.tex b/presentation/main.beamer.tex new file mode 100644 index 0000000..3ab411e --- /dev/null +++ b/presentation/main.beamer.tex @@ -0,0 +1,4 @@ +\documentclass[aspectratio=43]{beamer} +\usetheme{Luebeck} +\setbeamercolor{background canvas}{bg=lightgray} +\input{main} diff --git a/presentation/main.bib b/presentation/main.bib new file mode 100644 index 0000000..7f8cb0d --- /dev/null +++ b/presentation/main.bib @@ -0,0 +1,223 @@ +@online{wikipedia-linksys, + author = {Wikipedia}, + title = {Linksys WRT54G series}, + date = {2018}, + url = {https://en.wikipedia.org/wiki/Linksys_WRT54G_series} +} +@online{wifiplanet-story, + author = {Wi-Fi Planet}, + title = {The Open Source WRT54G Story}, + date = {2005}, + url = {http://www.wi-fiplanet.com/tutorials/article.php/3562391} +} +@online{linux-kconfig, + author = {Linux Developers}, + title = {Kconfig Language}, + date = {2018}, + url = {https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt} +} +@online{gnu-autotools, + author = {Free Software Foundation}, + title = {An Introduction to the Autotools}, + date = {2018}, + url = {https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html} +} +@online{kitware-cmake, + author = {Kitware}, + title = {CMake}, + date = {2018}, + url = {https://cmake.org/} +} +@online{scons, + author = {SCons Foundation}, + title = {SCons}, + date = {2018}, + url = {http://scons.org/} +} +@online{fsf-quilt, + author = {Free Software Foundation}, + title = {Quilt}, + date = {2018}, + url = {http://savannah.nongnu.org/projects/quilt/} +} +@online{buildroot, + author = {Peter Korsgaard}, + title = {Buildroot}, + date = {2018}, + url = {https://buildroot.org/} +} +@online{openwrt-devices, + author = {OpenWrt}, + title = {Table of Hardware}, + date = {2018}, + url = {https://openwrt.org/toh/start} +} +@online{openwrt-requirements, + author = {OpenWrt}, + title = {Supported Devices}, + date = {2018}, + url = {https://openwrt.org/supported_devices} +} +@online{openwrt-packages, + author = {OpenWrt}, + title = {Package Table}, + date = {2018}, + url = {https://openwrt.org/packages/table/start} +} +@online{debian-website, + author = {Debian Project (Software in the Public Interest)}, + title = {Debian}, + date = {2018}, + url = {https://www.debian.org/} +} +@book{starch-how_linux_works, + title = {How Linux Works}, + subtitle = {What Every Superuser Should Know}, + author = {Brian Ward}, + year = {2014}, + publisher = {No Starch Press}, + url = {https://nostarch.com/howlinuxworks2} +} +@book{starch-linux_command_line, + title = {The Linux Command Line}, + subtitle = {A Complete Introduction}, + author = {William E. Shotts Jr.}, + year = {2012}, + publisher = {No Starch Press}, + url = {https://nostarch.com/tlcl} +} +@book{prentice-c_programming_language, + title = {C Programming Language}, + author = {Brian W. Kernighan, Dennis M. Ritchie}, + year = {1988}, + publisher = {Prentice Hall}, + url = {https://www.amazon.com/Programming-Language-2nd-Brian-Kernighan/dp/0131103628} +} +@book{wesley-c_primer_plus, + title = {C Primer Plus}, + author = {Stephen Prata}, + year = {2013}, + publisher = {Addison-Wesley Professional}, + url = {https://www.amazon.com/C-Primer-Plus-Developers-Library-ebook/dp/B00GWLPX76} +} +@book{oreilly-understanding_and_using_c_pointers, + title = {Understanding and Using C Pointers}, + subtitle = {Core Techniques for Memory Management}, + author = {Richard M Reese}, + year = {2013}, + publisher = {O'Reilly Media}, + url = {http://shop.oreilly.com/product/0636920028000.do} +} +@book{oreilly-managing_projects_with_gnu_make, + title = {Managing Projects with GNU Make}, + subtitle = {Use the Power of GNU Make for Building Anything}, + author = {Robert Mecklenburg}, + year = {2004}, + publisher = { O'Reilly Media}, + url = {http://shop.oreilly.com/product/9780596006105.do} +} +@book{turnbull-the_docker_book, + title = {The Docker Book}, + subtitle = {Containerization is the new virtualization}, + author = {James Turnbull}, + year = {2014}, + publisher = {James Turnbull}, + url = {https://www.dockerbook.com/} +} +@online{openwrt-ubus, + author = {OpenWrt}, + title = {ubus (OpenWrt micro bus architecture)}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/techref/ubus} +} +@online{openwrt-ubox, + author = {OpenWrt}, + title = {ubox}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/techref/ubox} +} +@online{openwrt-libubox, + author = {OpenWrt}, + title = {libubox}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/techref/libubox} +} +@online{openwrt-uci, + author = {OpenWrt}, + title = {The UCI System}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/uci} +} +@online{openwrt-libuci, + author = {OpenWrt}, + title = {UCI (Unified Configuration Interface) - Technical Reference}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/techref/uci?s[]=libuci} +} +@online{lutfi-ubus, + author = {L.M. Lutfi Sh.}, + title = {OpenWRT Modules: U-BUS}, + date = {2018}, + url = {http://technostuff.blogspot.hr/2017/03/openwrt-modules-u-bus.html} +} +@online{lutfi-ubox_ubus, + author = {L.M. Lutfi Sh.}, + title = {OpenWRT Modules (UBOX, UBUS, etc.)}, + date = {2018}, + url = {http://technostuff.blogspot.hr/2017/03/openwrt-modules-ubox-ubus-etc.html} +} +@online{openwrt-log, + author = {OpenWrt}, + title = {System log in OpenWrt}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/howto/log.essentials} +} +@online{openwrt-rpc_guide, + author = {OpenWrt}, + title = {RPC daemon}, + date = {2018}, + url = {https://openwrt.org/docs/guide-developer/rpcd} +} +@online{openwrt-rpc_techref, + author = {OpenWrt}, + title = {rpcd (OpenWrt ubus RPC backend server)}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/techref/rpcd} +} +@online{openwrt-procd, + author = {OpenWrt}, + title = {procd (process management daemon) - Technical Reference}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/techref/procd} +} +@online{torvalds-git, + author = {Linus Torvalds}, + title = {Git}, + date = {2018}, + url = {https://git-scm.com/} +} +@book{chacon-pro_git, + title = {Pro Git}, + author = {Scott Chacon, Ben Straub}, + year = {2014}, + publisher = {Apress}, + url = {https://git-scm.com/book} +} +@online{openwrt-opkg, + author = {OpenWrt}, + title = {OPKG Package Manager}, + date = {2018}, + url = {https://wiki.openwrt.org/doc/techref/opkg} +} +@online{boost, + title = {Boost}, + date = {2018}, + url = {https://www.boost.org/} +} +@book{starch-linux-programming-interface, + title = {Linux Programming Interface}, + author = {Michael Kerrisk}, + year = {2010}, + publisher = {No Starch Press}, + url = {http://man7.org/tlpi/} +} diff --git a/presentation/main.handout.tex b/presentation/main.handout.tex new file mode 100644 index 0000000..24a942e --- /dev/null +++ b/presentation/main.handout.tex @@ -0,0 +1,6 @@ +\documentclass[aspectratio=43, handout]{beamer} +\usetheme{Luebeck} +\usecolortheme{seagull} +\usepackage{pgfpages} +\pgfpagesuselayout{4 on 1}[a4paper, border shrink=10mm, landscape] +\input{main} diff --git a/presentation/main.slides.tex b/presentation/main.slides.tex new file mode 100644 index 0000000..9d87cf9 --- /dev/null +++ b/presentation/main.slides.tex @@ -0,0 +1,4 @@ +\documentclass[aspectratio=43, handout]{beamer} +\usetheme{Luebeck} +\setbeamercolor{background canvas}{bg=lightgray} +\input{main} diff --git a/presentation/main.tex b/presentation/main.tex new file mode 100644 index 0000000..121f342 --- /dev/null +++ b/presentation/main.tex @@ -0,0 +1,14 @@ +\input{preamble} + +\begin{document} + \input{title.tex} + \input{about.tex} + + \part{OpenWrt Basics} + \input{openwrt_basics.tex} + + \part{OpenWrt Modules} + \input{openwrt_modules.tex} + + \input{bibliography.tex} +\end{document} diff --git a/presentation/openwrt_basics.tex b/presentation/openwrt_basics.tex new file mode 100644 index 0000000..5761f6d --- /dev/null +++ b/presentation/openwrt_basics.tex @@ -0,0 +1,131 @@ +\section{OpenWrt Overview} + +\subsection{Project Information} +\begin{frame}{Project Information} + \pause + \begin{itemize}[<+-|alert@+>] + \item OpenWrt is an open source meta-distibution and platform/framework for embedded devices. + \item Named after Linksys WRT54G and based on its firmware source code and the uClibc buildroot project~\cite{wikipedia-linksys}~\cite{wifiplanet-story}. + \item Today, OpenWrt supports over 1300 devices. + \item No formal legal entity behind the project, but supported by all major players. + \item Version 17.01.4 is the current stable release. + \end{itemize} +\end{frame} + +\subsection{Technical Information} +\begin{frame}{Technical Information} + \pause + \begin{itemize}[<+-|alert@+>] + \item Open source GNU/Linux distribution (\url{https://openwrt.org/}). + \item Small and modular design. + \item Relatively low hardware constraints. Minimum 4 MB flash and 32 MB RAM~\cite{openwrt-requirements}. + \item Supports over 1300 devices (ARM, MIPS, x86, PowerPC, AVR32, ARC)~\cite{openwrt-devices}. + \item Pre-assembled images at disposal (\url{https://downloads.openwrt.org/}). + \item Package management (opkg), process management (procd), RPC (ubusd), web interface (luci), unified configuration interface (uci), network interface (netifd). + \item Large number of available packages (> 3500)~\cite{openwrt-packages}. + \item Custom application without the need to re-build entire firmware. + \item OTA update (sysupgrade). + \end{itemize} +\end{frame} + +\subsection{Why OpenWrt?} +\begin{frame}{Why OpenWrt?} + \pause + \begin{itemize}[<+-|alert@+>] + \item \href{https://openwrt.org/reasons_to_use_lede}{Official} reasons to use OpenWrt. + \item Superior to the stock firmware of a router or embedded device. + \item \textbf{OpenWrt is a platform/framework for IoT projects.} + \end{itemize} +\end{frame} + +\section{OpenWrt Structure and Design} + +\subsection{Highlevel Overview} +\begin{frame}{Highlevel Overview} + \pause + \begin{itemize}[<+-|alert@+>] + \item OpenWrt = GNU/Linux + Network Applications + OpenWrt Modules. + \item OpenWrt doesn't include complete source code. + \item Composed of externaly referenced components. + \item Consists of toolchain, kernel, packages, patches and configuration files. + \item Package feed mechanism. + \end{itemize} +\end{frame} + +\begin{frame}{Highlevel Overview} + \fitframegraphics{openwrt-composition} +\end{frame} + +\subsection{Build System} +\begin{frame}{Build System} + \pause + \begin{itemize}[<+-|alert@+>] + \item Based on Buildroot~\cite{buildroot}. + \item Automates process of porting software to specific hardware. + \item Uses Kconfig~\cite{linux-kconfig} for configuration of features. + \item Provides integrated cross-compiler toolchain. + \item Provides abstraction for Autotools~\cite{gnu-autotools}, CMake~\cite{kitware-cmake}, SCons~\cite{scons}. + \item Provides patch management with Quilt~\cite{fsf-quilt}. + \item Provides download, patch, configure, compile and packaging workflow. + \end{itemize} +\end{frame} + +\section{Building and Running OpenWrt} + +\subsection{Preparing Host} +\begin{frame}{Preparing Host} + \pause + \begin{itemize}[<+-|alert@+>] + \item Build system works on Linux, BSD or macOS operating system. \textbf{Microsoft Windows is NOT supported.} + \item Recommendation is to use Linux distribution, specifically Debian~\cite{debian-website}. + \item \href{https://openwrt.org/docs/guide-developer/build-system/install-buildsystem}{Official} documentation describing OpenWrt build system requirements in details. + \item Personal recommendation is to use a \href{https://github.com/hvarga/openwrt-application-development/blob/master/presentation/resources/Dockerfile}{custom made} Docker Image which includes everything necessary for building OpenWrt. + \item Download OpenWrt project source code. \\ + \inlinecode{git clone https://git.openwrt.org/openwrt/openwrt.git} + \item Checkout latest stable version. \\ + \inlinecode{git checkout v17.01.4} + \end{itemize} +\end{frame} + +\subsection{Configuring Build System} +\begin{frame}{Configuring Build System} + \pause + \begin{itemize}[<+-|alert@+>] + \item Prepare package feed. \\ + \inlinecode{cp feeds.conf.default feeds.conf} + \item Update package index based on the information available in the feeds. \\ + \inlinecode{./scripts/feeds update -a} + \item Make all packages in feeds available in the configuration menu. \\ + \inlinecode{./scripts/feeds install -a} + \item Start the build system configuration interface and select target platform, packages to be compiled, packages to be included in the firmware file, kernel options, and much more. \\ + \inlinecode{make menuconfig} + \end{itemize} +\end{frame} + +\begin{frame}{Configuring Build System} + \fitframegraphics{menuconfig} +\end{frame} + +\begin{frame}{Configuring Build System} + Example of targets and its usage. + \pause + \begin{itemize}[<+-|alert@+>] + \item Dedicated hardware. Example, choose \inlinecode{Broadcom BCM27xx} for Target System and \inlinecode{BCM2710} for Subtarget to configure build system for Raspberry Pi 3. + \item Virtualized using QEMU. Example, choose \inlinecode{MIPS Malta CoreLV board (qemu)} for Target System to get a QEMU compatible image. + \item Containerized environment using Docker. Example, choose \inlinecode{x86} for Target System to get an image which can be imported into Docker. + \end{itemize} +\end{frame} + +\subsection{Building and Running Image} +\begin{frame}[fragile]{Building and Running Image} + \pause + \begin{itemize}[<+-|alert@+>] + \item It is assumed that you have choosen \textit{MIPS Malta CoreLV board (qemu)} for Target System. + \item Build the final image. \\ + \inlinecode{make} + \item Images can be found under the \inlinecode{./bin/targets/} directory. For \inlinecode{MIPS Malta CoreLV board (qemu)}, images are stored in \inlinecode{.bin/targets/malta/le/}. + \item Run the image in QEMU. \\ + \inlinecode{cd ./bin/targets/malta/le} \\ + \inlinecode{qemu-system-mipsel -kernel lede-malta-le-vmlinux-initramfs.elf -nographic} + \end{itemize} +\end{frame} \ No newline at end of file diff --git a/presentation/openwrt_modules.tex b/presentation/openwrt_modules.tex new file mode 100644 index 0000000..abfd0d6 --- /dev/null +++ b/presentation/openwrt_modules.tex @@ -0,0 +1,65 @@ +\section{Modules Overview} + +\subsection{List of Core Modules} +\begin{frame}{List of Core Modules} + \pause + \begin{description}[<+-|alert@+>] + \item[ubox] General purpose library which provides features like an event loop, binary blob message formatting and handling, linked list, and some JSON helpers~\cite{openwrt-ubox}~\cite{openwrt-libubox}~\cite{lutfi-ubox_ubus}~\cite{openwrt-log}. + \item[uci] Configuration interface aimed to centralize the configuration of OpenWrt~\cite{openwrt-uci}~\cite{openwrt-libuci}. + \item[ubus] Sofware communication bus which provides communication between various daemons and applications in OpenWrt~\cite{openwrt-ubus}~\cite{lutfi-ubus}~\cite{lutfi-ubox_ubus}~\cite{openwrt-rpc_guide}~\cite{openwrt-rpc_techref}. + \item[procd] Process manager~\cite{openwrt-procd}. + \item[opkg] Package manager~\cite{openwrt-opkg}. + \end{description} +\end{frame} + +\subsection{Logical Structure} +\begin{frame}{Logical Structure} + \fitframegraphics{openwrt-modules} +\end{frame} + +\section{ubox} + +\subsection{Overview} +\begin{frame}{Overview} + \begin{itemize}[<+-|alert@+>] + \item Collection of C utility functions for OpenWrt. + \item Composed of two components: \href{https://git.openwrt.org/project/libubox.git}{libubox} and \href{https://git.openwrt.org/project/ubox.git}{ubox}. + \item General purpose library (think \href{https://wiki.gnome.org/Projects/GLib}{glib} and \href{https://www.boost.org/}{boost} only micro size) and utilities. + \item Provides polling, event handling, socket helper functions, logging, MD5 hashing, generating/parsing tagged binary data, AVL binary-tree balancing, JSON handling, task queueing/completion tracking, endian conversion, Base64 encoding/decoding, linked lists and key value lists. + \item Provides centralized logging systems with logd (think Syslog) and logread. + \end{itemize} +\end{frame} + +\subsection{uloop} + +\subsubsection{Problem Domain} +\begin{frame}{Problem Domain} + \fitframegraphics{event-loop} +\end{frame} + +\subsubsection{Features} +\begin{frame}{Features} + \begin{itemize}[<+-|alert@+>] + \item I/O event notification loop. + \item Its job is to poll file descriptors, run timers, manage child processes. + \item Event loop is backed by epoll and kqueue~\cite{starch-linux-programming-interface}. + \end{itemize} +\end{frame} + +\subsubsection{Code Snippet} +\begin{frame}[fragile, allowframebreaks]{Code Snippet} + \lstinputlisting[language=C]{uloop-hello-world.c} +\end{frame} + +\section{uci} + +\subsection{Overview} +\begin{frame}{Overview} + \begin{itemize}[<+-|alert@+>] + \item Common configuration format used by every application running on OpenWrt. + \item Centralize the whole configuration of a device running OpenWrt. + \item Configuration file is exposed with the \inlinecode{uci} utility and \inlinecode{libuci} C library. + \item New application should use the uci system. + \item Existing non-uci compatible application can be made compatible by writing wrapper. + \end{itemize} +\end{frame} diff --git a/presentation/package_configuration.tex b/presentation/package_configuration.tex new file mode 100644 index 0000000..4ecfd2c --- /dev/null +++ b/presentation/package_configuration.tex @@ -0,0 +1,43 @@ +\definecolor{dkgreen}{rgb}{0,0.6,0} +\definecolor{gray}{rgb}{0.5,0.5,0.5} +\definecolor{mauve}{rgb}{0.58,0,0.82} +\definecolor{lbcolor}{rgb}{0.9,0.9,0.9} + +\lstset{ + showstringspaces=false, + columns=flexible, + basicstyle=\scriptsize\ttfamily, + numbers=left, + xleftmargin=2em, + frame=none, + framexleftmargin=1.5em, + numbersep=5pt, + numberstyle=\scriptsize\ttfamily\color{black!60}, + keywordstyle=\color{blue}, + commentstyle=\color{dkgreen}, + stringstyle=\color{mauve}, + breaklines=true, + postbreak=\mbox{\textcolor{red}{$\hookrightarrow$}\space}, + breakatwhitespace=true, + tabsize=4, + autogobble=true, + rulesepcolor=\color{blue}, + inputpath=resources +} + +\hypersetup { + bookmarksopen=true, + bookmarksopenlevel=4, + colorlinks, + linkcolor=., + citecolor=blue +} +\setcounter{tocdepth}{4} + +\addbibresource{main.bib} + +\WarningFilter{biblatex}{Patching footnotes failed} + +\graphicspath{ {resources/} } + +\setbeamertemplate{frametitle continuation}{} diff --git a/presentation/package_list.tex b/presentation/package_list.tex new file mode 100644 index 0000000..df8c5bf --- /dev/null +++ b/presentation/package_list.tex @@ -0,0 +1,13 @@ +\usepackage{listings} +\usepackage{lstautogobble} +\usepackage{FiraSans} +\usepackage{FiraMono} +\usepackage[T1]{fontenc} +\usepackage[type={CC},modifier={by-sa},version={3.0},]{doclicense} +\usepackage[backend=biber, sorting=none]{biblatex} +\usepackage{silence} +\usepackage{graphicx} +\usepackage{fontawesome} +\usepackage[utf8]{inputenc} +\usepackage{listings} +\usepackage[most]{tcolorbox} diff --git a/presentation/preamble.tex b/presentation/preamble.tex new file mode 100644 index 0000000..49f47cc --- /dev/null +++ b/presentation/preamble.tex @@ -0,0 +1,43 @@ +\input{package_list} +\input{package_configuration} + +\title{OpenWrt} +\subtitle{Application Development} +\author{Hrvoje Varga} +\date{} + +\beamertemplatenavigationsymbolsempty +\setbeamertemplate{bibliography item}{\insertbiblabel} +\useoutertheme{infolines} + +\AtBeginPart +{ + \begin{frame}[plain] + \partpage + \end{frame} +} + +\AtBeginSection[] +{ + \begin{withoutheadline} + \begin{frame} + \frametitle{Outline} + \tableofcontents[currentsection,sectionstyle=show/shaded,subsectionstyle=show/show/hide,subsubsectionstyle=show/show/show/hide] + \end{frame} + \end{withoutheadline} +} + +\makeatletter +\newenvironment{withoutheadline}{ + \setbeamertemplate{headline}[default] + \def\beamer@entrycode{\vspace*{-\headheight}} +}{} +\makeatother + +\newcommand{\fitframegraphics}[1] { + \centerline{\includegraphics[width=\textwidth, height=0.8\textheight, keepaspectratio]{#1}} +} + +\newcommand{\inlinecode}[1] { + \lstinline!#1! +} diff --git a/presentation/resources/Dockerfile b/presentation/resources/Dockerfile new file mode 100644 index 0000000..118f6c3 --- /dev/null +++ b/presentation/resources/Dockerfile @@ -0,0 +1,44 @@ +# Based on requirements [1], start from Debian 9.3. +# [1] https://openwrt.org/docs/guide-developer/build-system/install-buildsystem +FROM debian:9.3 + +LABEL maintainer="hrvoje.varga@gmail.com" +LABEL build="docker build -t hvarga/openwrt-builder ." +LABEL run="docker run -it --rm -v ${PWD}:/home/openwrt/work hvarga/openwrt-builder" + +# Install OpenWrt build dependancies listed in the official requirements [1]. +RUN apt-get update -q && DEBIAN_FRONTEND=noninteractive apt-get install -qy \ + build-essential \ + libncurses5-dev \ + gawk \ + git \ + subversion \ + libssl-dev \ + gettext \ + zlib1g-dev \ + unzip \ + wget \ + python \ + file + +# Install QEMU so that we can run OpenWrt image as a virtualized machine. +RUN DEBIAN_FRONTEND=noninteractive apt-get install -qy qemu + +# Install a text editor. +RUN DEBIAN_FRONTEND=noninteractive apt-get install -qy vim + +# Cached packages are not needed anymore and they just increase the image size. +# Remove cached packages. +RUN rm -rf /var/lib/apt/lists/* + +# Official requirements [1] state that we should do everything as normal user. +# root user or sudo must not be used. +# Add unprivileged user which will be used to build OpenWrt. +RUN useradd openwrt --create-home --uid 1000 + +# Switch to the unprivileged user and set default working directory. +USER openwrt +WORKDIR /home/openwrt/work + +# Configure BASH as an entrypoint. +ENTRYPOINT ["bash"] \ No newline at end of file diff --git a/presentation/resources/event-loop.pdf b/presentation/resources/event-loop.pdf new file mode 100644 index 0000000..03bed08 Binary files /dev/null and b/presentation/resources/event-loop.pdf differ diff --git a/presentation/resources/menuconfig.png b/presentation/resources/menuconfig.png new file mode 100644 index 0000000..7e055c7 Binary files /dev/null and b/presentation/resources/menuconfig.png differ diff --git a/presentation/resources/openwrt-composition.pdf b/presentation/resources/openwrt-composition.pdf new file mode 100644 index 0000000..ce16789 Binary files /dev/null and b/presentation/resources/openwrt-composition.pdf differ diff --git a/presentation/resources/openwrt-modules.pdf b/presentation/resources/openwrt-modules.pdf new file mode 100644 index 0000000..f355d67 Binary files /dev/null and b/presentation/resources/openwrt-modules.pdf differ diff --git a/presentation/resources/uloop-hello-world.c b/presentation/resources/uloop-hello-world.c new file mode 100644 index 0000000..2c2a029 --- /dev/null +++ b/presentation/resources/uloop-hello-world.c @@ -0,0 +1,30 @@ +#include + +static struct uloop_timeout my_event_timer; + +static void my_event_handler(struct uloop_timeout *timeout) +{ + // if we want to make a repeatable event, set the timer again by calling uloop_timeout_set() +} + +static void set_event(void) +{ + // configure function which will be called when timer is expired + my_event_timer.cb = my_event_handler; + // schedule a timer which will timeout in one second from now + uloop_timeout_set(&my_event_timer, 1000); +} + +int main(void) +{ + // initialize uloop, must be called before uloop_run() + uloop_init(); + // add a one-shot timer task + set_event(); + // start main event loop, which is a blocking operation and will run continuously until we set the global variable uloop_cancelled to true + uloop_run(); + // cleanup resources used by uloop + uloop_done(); + + return 0; +} diff --git a/presentation/title.tex b/presentation/title.tex new file mode 100644 index 0000000..49b1638 --- /dev/null +++ b/presentation/title.tex @@ -0,0 +1,14 @@ +\begin{frame}[plain] + \IfFileExists{current_commit.tex} { + \input{current_commit.tex} + \addtobeamertemplate{title page}{} { + \begin{center} + \tiny \commitdate + \\ + \tiny \commitid + \end{center} + } + } + + \titlepage +\end{frame}