diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..67e972d --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,18 @@ +all: clean html man + +html: + @echo generating html... + @./nanodoc html + +man: + @echo generating manpages... + @./nanodoc man + +clean: + @echo cleaning... + @rm -rf html man nav.html + @sed -i -e 's:index.html">.*:html">NAME:' static/head.html + @sed -i -e 's:Subtitle">.*:Subtitle">DESC:' static/head.html + @sed -i -e 's:libdevuansdk-.*:libdevuansdk-VERSION:' static/foot.html + +.PHONY: all html man clean diff --git a/doc/configuration.7.md b/doc/configuration.7.md new file mode 100644 index 0000000..f28c2e4 --- /dev/null +++ b/doc/configuration.7.md @@ -0,0 +1,52 @@ +configuration +============= + +much of the `libdevuansdk` configuration is done in `libdevuansdk/config`. here +you can edit the defaults if you wish to do something your needs are expressing. + +## config file + +`vars` and `arrs` are global arrays holding other global variables and arrays. +this is required for `zuper` and helps a lot with debugging. if you declare new +variables or arrays, add them to `vars` and `arrs`, respectively. + +* `os` + holds the name of the distro being worked on. + +* `release` + holds the release name of the distro. used for apt repos mostly. + +* `version` + current version of the distro being worked on. + +* `mirror` + a mirror holding the packages for `debootstrap`. + +* `section` + sections of the repo. for adding in `/etc/apt/sources.list`. separate them + with whitespaces. + +* `image_name` + output name of the raw image. if you declare `device_name`, it will be added. + `arm-sdk` does this. + +* `core_packages` + this array holds the core packages that will be installed in the bootstrap + process. + +* `base_packages` + this array holds the base packages that will be installed later in the + bootstrap process. + +* `purge_packages` + this array holds the packages that will get purged at the end of the bootstrap + process. + + +## overriding things + +to be able to override specific unwanted functions of libdevuansdk, consider +sourcing it earlier in the process of initialization. + +it is possible to override default variables, or even functions without the need +of editing libdevuansdk. share a patch with me if you wish :) diff --git a/doc/creating_wrappers.7.md b/doc/creating_wrappers.7.md new file mode 100644 index 0000000..76a3da3 --- /dev/null +++ b/doc/creating_wrappers.7.md @@ -0,0 +1,90 @@ +creating wrappers around libdevuansdk +===================================== + +libdevuansdk holds all the helper functions you might need, but it does not +allow you to simply use it in a completely automated fashion. for that you +will have to wrap some zsh around libdevuansdk. + +there are a few mandatory variables that you are required to declare before +sourcing libdevuansdk. otherwise libdevuansdk might write to some places of the +system you wouldn't want to. + +## requirements + +before sourcing it, libdevuansdk assumes you already loaded and initialized +the [zuper](https://github.com/dyne/zuper) zsh library. + + +### mandatory variables + +* `$R` + the root directory of your wrapper. in almost every situation you can set + it as `$PWD` + +* `$workdir` + the working directory of the current "build". a sane default is + `$R/tmp/workdir` + +* `$strapdir` + the bootstrap directory of the current "build". it holds the rootfs when + you debootstrap. sane default: `$workdir/rootfs` + +* `$arch` + the CPU architecture of the current "build". values like: `amd64`, `i386`, + `armhf`, etc... + + +### Optional variables + +* `$extra_packages` + this should hold an array of packages that exist in the devuan package tree. + they will get installed as a part of the bootstrap process. + +* `$purge_packages` + this is an array that holds a list of packages that will get removed at the + final steps of the bootstrap process. note that this array is not empty by + default, so you should only add to it in your wrapper, not override it. + just to be safe. + +* `$size` + This variable will hold the value in MiB for `dd` to know how many zeroes it + should put in the raw image. + ex: `size=1337` + +* `$parted_type` + if you are creating a raw (dd-able) image, this variable will tell + libdevuansdk how to partition that image. either `dos` or `gpt`. + +* `$parted_boot` + used if `$parted_type=dos`. it holds the values for `parted` and the + formatting of the `boot` partition. + ex: `parted_boot="fat32 2048s 264191s"`. + see the `image_partition_raw_dos()` function in `libdevuansdk/zlibs/imaging` + for a better understanding on how the variable is used. + +* `$parted_root` + used if `$parted_type=dos`. it holds the values for `parted` and the + formatting of the `root` partition. + ex: `parted_root="ext4 264192s 100%"`. + see the `image_partition_raw_dos()` function in `libdevuansdk/zlibs/imaging` + for a better understanding on how the variable is used. + +* `$gpt_boot` + used if `$parted_type=gpt`. it is an array holding the start and end values + for partitioning the `boot` partition. + ex: `gpt_boot=(8192 32768)` + see the `image_partition_raw_gpt()` function in `libdevuansdk/zlibs/imaging + for a better understanding on how the variable is used. + +* `$gpt_root` + used if `$parted_type=gpt`. it is an array holding the start value for + partitioning the `root` partition. + ex: `gpt_root=(40960)` + currently libdevuansdk chooses this as a startpoint, and maxes out remaining + available space. again, see the `image_partition_raw_gpt()` function for a + better understanding. + +* `$qemu_bin` + declare this if you are bootstrapping for an architecture different than + yours. it should hold the path to `qemu-user-static` or a similarly named + statically compiled qemu for userspace. diff --git a/doc/helper_functions.7.md b/doc/helper_functions.7.md new file mode 100644 index 0000000..bf01c52 --- /dev/null +++ b/doc/helper_functions.7.md @@ -0,0 +1,54 @@ +helper functions +================ + +you can find useful helper functions in `libdevuansdk/zlibs/helpers`. they are +intended to help you with writing wrappers, as well as making my job easier +within developing libdevuansdk. some of these functions are required for +libdevuansdk to properly work as well. + + +## build_image_dist() +this function is kind of a wrapper function, mostly used in `arm-sdk` to build a +complete "dd-able" image from start to end. to run, it requires `$arch`, +`$size`, `$parted_type`, `$workdir`, and `$strapdir` to be declared. as well as +`$parted_root`, `$parted_boot` if `$parted_type=dos`, or `$gpt_root`, +`$gpt_boot` if `$parted_type=gpt`. see `creating_wrappers(7)` for insight on +these variables. + +the workflow of this function is bootstrapping a complete rootfs, creating a raw +image, installing/compiling a kernel, rsyncing everything to the raw image, and +finally, compressing the raw image. + + +## devprocsys() +this function is a simple helper function that takes two arguments: `watdo` and +`werdo`. it mounts or umounts `/sys`, `/dev`, `/dev/pts`, and `procfs` where you +tell it to. for example: + +``` +devprocsys mount $strapdir +devprocsys umount $strapdir +``` + + +## findloopmapp() +this functions takes the raw image and finds a free loopdevice for it to be +mounted. it calls `losetup(8)` and `kpartx(8)`. + + +## qemu_install_user() +helper function to install the userspace qemu to `$strapdir`. + + +## dpkgdivert() +this one takes two arguments, `watdo` and `werdo` (much like `devprocsys`). it +will create a dpkg diversion in the place you tell it to and remove invoke-rc.d +so that apt doesn't autostart daemons when they are installed. + + +## enablessh() +this function will allow root login with password in the bootstrapped rootfs. + + +## silly() +a funny function printing out random messages. diff --git a/doc/libdevuansdk.7.md b/doc/libdevuansdk.7.md new file mode 100644 index 0000000..416b5f0 --- /dev/null +++ b/doc/libdevuansdk.7.md @@ -0,0 +1,48 @@ +index +===== + +`libdevuansdk` is a shell script library intended to unify the use and creation +of various functions spread throughout devuan's various sdks. + +devuan's sdks are designed to be used interactively from a terminal, as +well as from shell scripts. libdevuansdk uses the functionality of the +[zuper](https://github.com/dyne/zuper) zsh library, but it does not include +it. you are required to include it in your sdk. however, `libdevuansdk` +requires the following packages to be installed: + +``` +zsh debootstrap sudo kpartx cgpt xz-utils +``` + +## notes + +to support the development, you are welcome to open issues on problems and +bugs you encounter. open merge requests of patches or simply get involved +in other tasks evident on + +## acknowledgments + +Devuan's SDK was originally conceived during a period of residency at the +Schumacher college in Dartington, UK. Greatly inspired by the laborious and +mindful atmosphere of its wonderful premises. + +The Devuan SDK is Copyright (c) 2015-2016 by the Dyne.org Foundation + +Devuan SDK components are designed, written and maintained by: + +- Ivan J. +- Denis Roio +- Enzo Nicosia + +This source code is free software: you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) +any later version. + +This software 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 for +more details. + +You should have received a copy of the GNU General Public License along +with this source code. If not, see . diff --git a/doc/nanodoc b/doc/nanodoc new file mode 100755 index 0000000..dcb2cf2 --- /dev/null +++ b/doc/nanodoc @@ -0,0 +1,75 @@ +#!/bin/sh +# Copyright (c) 2016 parazyd +# nanodoc is written and maintained by parazyd +# +# This file is part of arm-sdk +# +# This source code is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This software 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 for more details. +# +# You should have received a copy of the GNU General Public License +# along with this source code. If not, see . + +org="parazyd | dyne.org" +name=libdevuansdk +version=0.2 +desc="common library for devuan's sdks" + +pages=" + libdevuansdk.7 + configuration.7 + workflow.7 + helper_functions.7 + creating_wrappers.7 +" + +generate_manpages() { + for page in $pages; do + ronn -r --manual="$name" --organization="$org" ${page}.md + done + + mkdir -p man/7 + mv *.7 man/7 +} + +generate_html() { + mkdir -p html + sed -i -e 's/NAME/'"$name"'/' -e 's/DESC/'"$desc"'/g' static/head.html + sed -i -e 's/VERSION/'$version'/' static/foot.html + + for page in $pages; do + pagetitle=$(sed 1q ${page}.md) + printf '
  • %s
    • \n' $page "$pagetitle" >> nav.html + done + + printf "
    \n" >> nav.html + + for page in $pages; do + printf "\thtml/%s\n" $page + cat static/head.html > html/${page}.html + cat nav.html >> html/${page}.html + python -m markdown ${page}.md >> html/${page}.html + cat static/foot.html >> html/${page}.html + + pagetitle=$(sed 1q ${page}.md) + sed -i -e 's/TITLE/'"$pagetitle"'/' html/${page}.html + sed -i -e 's/'$page'.html" class="notPage/'$page'.html" class="thisPage/' html/${page}.html + done + + ln -sf libdevuansdk.7.html html/index.html + #cat nav.html + rm -f nav.html +} + +case $1 in + man) generate_manpages && exit 0 ;; + html) generate_html && exit 0 ;; + *) exit 1 ;; +esac diff --git a/doc/static/foot.html b/doc/static/foot.html new file mode 100644 index 0000000..f8b3678 --- /dev/null +++ b/doc/static/foot.html @@ -0,0 +1,11 @@ + +
    + + + + + diff --git a/doc/static/head.html b/doc/static/head.html new file mode 100644 index 0000000..ce9fc29 --- /dev/null +++ b/doc/static/head.html @@ -0,0 +1,199 @@ + + + + + TITLE + + + + + + + +
    +