Scripts to automatically create a Debian rootfs image and/or a complete, bootable SD-card.
Author: Ingmar Klein (ingmar.klein@hs-augsburg.de) Created in scope of the Master project, winter semester 2012/2013 under the direction of Professor Nik Klever, at the University of Applied Sciences Augsburg.
This program (including documentation) is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License version 3 (GPLv3; http://www.gnu.org/licenses/gpl-3.0.html ) for more details.
- A SERIAL CONNECTION to the Allwinner A10 device is HIGHLY RECOMMENDED for this procedure.
Debugging is more or less impossible without it! - Most of the descriptions below assume that you are able to connect to the Allwinner A10 device via serial connection!!!
- A working INTERNET CONNECTION is mandatory and must be available RIGHT AWAY when running the script! So please make sure to be connected before starting the script.
This Readme should explain how to use the debian build-scripts. It also explains the settings and their meaning.
- Host System Requirements
- Files
- Settings
- Running the script (no parameters)
- Running the script with call parameters (special functions)
- DEBUGGING and Log-Files
- Logging In
- Host System Requirements
You need a machine with at least Debian Squeeze/Stable (better Wheezy/Testing), or Ubuntu 11.04. (or better newer) . Default installs! If you did a minimal install of something similar, you will probably have to install a few extra packages, before being able to run the script.
Enough disk space for the build process (~4GB free space) and maybe 512MB RAM. Internet connection is mandatory for this script (on the host machine, not on the Allwinner A10 device).
No internet connection equals no build process!
You will need root priviliges! Either through the sudo package and the corresponding sudoers file, or by running the script as root.
HINT:
Works perfectly fine in a Virtual Machine, too. Ran dozens of builds in Virtualbox with Ubuntu and/or Debian installed there.
- Files
-
build_debian_system.sh : Main script file, running the functions defined in the "build_functions.sh". This is what you run in shell.
-
build_funtions.sh : As already mentioned, this includes the main build and some helper funtions that are used in the "build_debian_system.sh"
-
general_settings.sh: File for all settings and configurations. Here you define what the output of the scripts will look like.
- Settings
ATTENTION:
You must (!) edit the "general_settings.sh" to fit your host system and your needs, before running the main script!
Most of the settings are either self-explanatory, or already commented in the file itself. I'll now list the settings that you absolutely must change/edit/check:
- host_os: Either Debian or Ubuntu
- output_dir_base: This sets the local path for all the files generated by the script
- nameserver_addr: Without the correct setting for your network environment, the build process will most likely fail.
- root_password: As the name suggests, this sets the systems root password
- username: Name for the normal user to create (needed for the graphical login)
- user_password: Password for the user
All other settings are optional and CAN, but don't necessarily need to be changed! <-- Unless commented otherwise in the script code!
Note: The variable "additional_packages" is just a list of packages that should be installed. So, browse the debian package list ( http://packages.debian.org ) and add the packages that you want to the list. These will then be included in the resulting rootfs, if nothing goes wrong.
- Running the script
Running the script in full mode, utilizing all functions, is as easy as doing the following:
- Make sure that you downloaded/cloned all 3 script files (or the complete package) via git and edited the "general_settings.sh".
- Run
chmod +x build_debian_system.shif needed, to make the file executable. - Run the script itself by typing
sudo ./build_debian_system.shin a terminal window (NOT in a virtual console!). Of course you can also run the script as root directly, not using sudo. - Then follow the instructions on the screen! If nothing goes wrong, the only user-input required should be for choosing the keyboard layout and the default system locale and maybe then during the optional creation of the SD-card.
- The output should be in form of a compressed archive file (.tar.gz or .tar.bz2) containing the rootfs and kernel. The filename will be like set in "general_settings.sh".
- If you set the option to build a SD-Card, you will be asked to specify the correct device name for the SD-card, which then will be subsequently partitioned, formatted and filled with bootloader, rootfs and kernel.
- Running the script with call parameters (special functions)
The script now accepts three main call parameters. These are "build", "install". and "clean".
Descriptions:
build : This only runs the script's functions to build a new rootfs including kernel, but does not create a bootable SD-card. It is meant for those creating rootfs-archives for others to use, with known-to-work configurations.
install : Opposite of "build"! It will just download a prebuilt rootfs-archive + bootloader and will create a bootable SD-card using these files. This is meant for people not familiar with the build specifics who just want to create a SD-card with known-to-work rootfs configurations. The "install" parameter, however REQUIRES a valid second parameter, to work properly. This can either be "default", which then uses "default_rootfs_package_path" and "default_rootfs_package_name" from the "general_settings.sh" configuration file. Or you can pass the complete path+filename of a compressed (.tar.gz or .tar.bz2) rootfs-archive of your choice on to the script. The archive can be located online (for example 'http://www.tester.com/rootfs.tar.bz2' ) or on your local storage (for example '/home/tester/rootfs.tar.bz2' ). The script should be able to handle both cases just fine.
ATTENTION: At the moment the --bootloader option does not work correctly, so please use the settings in the general_settings.sh!
clean : Cleanup the build directory This option is used to delete either the files located in the cache or build directories, or even in both. As the script knows caching of apt-packages, it might sometimes be necessary to delete the old cache files before starting a new build. That's what --clean cache would be for. Respectively, --clean build would only delete the files and folders in the build directory and --clean all would do both.
Usage examples:
sudo ./build_debian_system.sh --build will run only the scripts build funtions to create a rootfs-archive according to your settings.
sudo ./build_debian_system.sh --install default will create a bootable SD-card containing the default-rootfs and bootloader specified in the "general_settings.sh"
sudo ./build_debian_system.sh --install http://www.tester.com/rootfs.tar.bz2 will download the named rootfs-archive and create a bootable SD-card with it (bootloader as set per "general_settings.sh")
sudo ./build_debian_system.sh --build will run only the scripts build funtions to create a rootfs-archive according to your settings.
sudo ./build_debian_system.sh --clean all will delete both the files in the build and cache directories.
sudo ./build_debian_system.sh --clean cache will only delete the files in the cache directory.
sudo ./build_debian_system.sh --clean build will only delete the files in the build directory.
Any wrong parameter leads to an error message and a short help text, explaining the valid usage options.
- DEBUGGING and Log-Files
There are several log files that get created while running the script. The main one, log.txt can be found under ${output_dir}/log.txt, where ${output_dir} is a variable that you set in the file general_settings.sh.
Several other log and error-log files get created in the root directory of the target-rootfs (the root filesystem that the script creates). If you need to find an error, have a look there, too. If the script comes that far, you can find the files in the output-archive (hint: ${output_dir}/${output_filename}, as set in general_settings.sh ) that the script creates.
Another useful file is the installed_packages.txt in the root folder of the compressed archive.
As the name suggests, this file contains a list (created by running dpkg -l) of all packages, included in that very rootfs.
If the error occurs before the creation of the output-archive, you might want to set the option clean_tmp_files in the general_settings.sh to no. This will cause the script to KEEP the temporary image file that is used for the rootfs creation. In order to debug you can then mount that very image file via loop, after the script failed.
- Logging In
The system gets built with a standard root account with password. The initial login data is the following:
User: root
Password: root
OR for the normal, default user account:
User: tester
Password: tester
If you want to change the root or user password, just run the command "passwd root" or "passwd user" (where user is the actual username) and follow the instructions. If you want to add a normal user account, run "adduser 'username' ", obviously with the name you want your user to have. If you edit the general_settings.sh the username and passwords might be different.
There is a Bug that causes the system to ask you to change the password on each system start, if the system time wasn't set when invoking passwd! Make sure that the system time is set to something else than 01/01/1970, if you intend to change the password!
HAVE FUN!