====== How to customize Buildroot ======
[[https://buildroot.org|Buildroot]] allows to keep customizations outside [[https://buildroot.org|Buildroot]] main project.
We are using this mechanism to extend & customize [[https://buildroot.org|Buildroot]] configuration for [[:liteSOM]] based projects and it is recommenced to start with one of our example to build //infrastructure// for your project.
Please take into account that below you can find one of the possible way how to customize [[https://buildroot.org|Buildroot]]; for more details please read [[https://buildroot.org/downloads/manual/manual.html|Buildroot User Manual]] and [[https://buildroot.org/downloads/manual/manual.html#outside-br-custom|Customizing the generated target filesystem]].
===== Project description =====
This project will allow you to build complete firmware image for [[liteSOM:liteboard]] and [[litesom:modulelcd|LCD display extension]] with resistive touchscreen.
Main intention is to keep all customizations outside Buildroot project but still allow user to configure [[https://www.kernel.org|kernel]], [[https://www.busybox.net|BusyBox]] and [[https://buildroot.org|Buildroot]] or to modify [[https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/devicetree/usage-model.txt|Device Tree]] without any problems.
===== Project setup =====
Download Buildroot release you want to use, for example
wget https://buildroot.org/downloads/buildroot-2016.11.1.tar.gz
Extract downloaded file
tar xf buildroot-2016.11.1.tar.gz
During this how to we will extend Buildroot setup by customizations from [[https://github.com/grinn-pub/examples|Grinn examples repository]], please clone this repository
git clone https://github.com/grinn-pub/examples.git
Tell Buildroot to use additional ''br2-external'' directory by setting (once per project setup) ''BR2_EXTERNAL'' variable as presented below
cd buildroot-2016-11.1
make BR2_EXTERNAL=/tmp/examples list-defconfigs
where ''/tmp/examples'' should point to cloned //Grinn examples// repository.
Target ''list-defconfigs'' shows list of available defconfigs. After built-in configs you should see configs provided by the external customizations (like //Grinn examples//).
make BR2_EXTERNAL=/tmp/examples list-defconfigs
Built-in configs:
acmesystems_aria_g25_128mb_defconfig - Build for acmesystems_aria_g25_128mb
acmesystems_aria_g25_256mb_defconfig - Build for acmesystems_aria_g25_256mb
[...]
External configs in "Grinn examples":
grinn_liteboard_lcd_res_defconfig - Build for grinn_liteboard_lcd_res
===== Project configuration =====
To configure Buildroot for [[:liteSOM]] with [[litesom:modulelcd|LCD sandwich]] please use ''grinn_liteboard_lcd_res_defconfig'' configuration template.
make grinn_liteboard_lcd_res_defconfig
====== Project compilation ======
You can compile project in this same way as usual
make all
====== Project output ======
Like for other [[https://buildroot.org|Buildroot]] based projects directory ''output/images/'' contains all files required to program [[liteSOM:liteboard]].
You can program //SD card// via following command
dd if=output/images/sdcard.img of=/dev/ bs=4M
====== More details about this customization ======
===== Buildroot configuration =====
.
├── configs
│ └── grinn_liteboard_lcd_res_defconfig
Complete configuration for [[https://buildroot.org|Buildroot]] is available in [[https://github.com/grinn-pub/examples/blob/master/configs/grinn_liteboard_lcd_res_defconfig|grinn_liteboard_lcd_res_defconfig]] file.
===== Device tree =====
.
├── board
│ └── grinn
│ └── liteboard-lcd-res
│ ├── imx6ul-liteboard-lcd-res.dts
│ ├── post-build.sh
[[https://buildroot.org|Buildroot]] configuration for ''liteboard'' doesn't contain any configuration for //LCD panel// nor //touchscreen// therefore this demo is using customized device tree file ([[https://github.com/grinn-pub/examples/blob/master/board/grinn/liteboard-lcd-res/imx6ul-liteboard-lcd-res.dts|imx6ul-liteboard-lcd-res.dts]]).
During kernel compilation this file will be compiled and output will be stored as ''imx6ul-liteboard-lcd-res.dtb''. You can find this file inside ''output/images'' directory.
Unfortunately on the target during boot procedure [[http://www.denx.de/wiki/U-Boot|U-Boot]] will try to load ''imx6ul-liteboard.dtb'' file which will be not available on //SD card//. Therefore every build [[https://buildroot.org|Buildroot]] via [[https://github.com/grinn-pub/examples/blob/master/board/grinn/liteboard-lcd-res/post-build.sh|post-build.sh]] script will adjust name of the ''Device Tree Blob'' file to the expected by the [[http://www.denx.de/wiki/U-Boot|U-Boot]].
===== Kernel configuration =====
.
├── board
│ └── grinn
│ └── liteboard-lcd-res
│ ├── linux.defconfig
Customized [[https://kernel.org|Linux]] configuration is stored in [[https://github.com/grinn-pub/examples/blob/master/board/grinn/liteboard-lcd-res/linux.defconfig|linux.defconfig]] file. It will be used by the [[https://buildroot.org|Buildroot]] to initialize proper kernel configuration.
===== Extra files =====
.
├── board
│ └── grinn
│ └── liteboard-lcd-res
│ └── rootfs
│ └── etc
│ ├── profile.d
│ │ └── tslib.sh
│ └── udev
│ └── rules.d
│ └── 60-touchscreen.rules
To simplify/unify board setup two config files should be available on running liteboard:
* [[https://github.com/grinn-pub/examples/blob/master/board/grinn/liteboard-lcd-res/rootfs/etc/profile.d/tslib.sh|/etc/profile.d/tslib.sh]] - to configure device for [[https://github.com/kergoth/tslib|tslib]] library,
* [[https://github.com/grinn-pub/examples/blob/master/board/grinn/liteboard-lcd-res/rootfs/etc/udev/rules.d/60-touchscreen.rules|/etc/rules.d/60-touchscreen.rules]] - to guarantee permanent name for the touchscreen device.
Each time when ''make all'' command will be called [[https://buildroot.org|Buildroot]] will automatically copy [[https://github.com/grinn-pub/examples/tree/master/board/grinn/liteboard-lcd-res/rootfs|rootfs]] directory to the ''output/target'' directory used in the next step to generate image for the [[liteSOM:liteboard]].