Build and customize your own Sage Debian Live USB ================================================= It is possible to build and customize your own Sage Debian Live. You should run Debian stable. Derivatives whose version of live-build package is 4.x should work as well but are not tested. Download sources ---------------- Install git package, go to a directory you want the sources to be cloned to and type :: git clone --branch master https://sagedebianlive.metelu.net/sagedebianlive.git cd sagedebianlive Install dependencies -------------------- To install required packages before your first build (you are assumed to be sudoer), go to the source directory and type :: ./build.sh install Consider using apt-cacher ------------------------- To save bandwidth, it is advised to use the package apt-cacher-ng :: sudo apt-get install apt-cacher-ng Customize your build -------------------- All customizable variables are set by default in the ``./config/default`` file, and some hints are given along the file as comments. To customize your build, you can overwrite some of those variables by creating a custom ``./config/`` file that will be run after the default file. It is better not to modify directly the ``./config/default`` file in order to keep your customizations when the default config will be updated. Select modules ~~~~~~~~~~~~~~ Most existing modules are selected by default. You can unselect some by removing them from the ``MODULES`` variable. Available modules are located in the ``./modules/`` directory. Note that some modules depend on some other modules, so you do not need to add them explicitely (though it does not harm), for example the mathematics/sagemath module depends on the mathematics/latex module. Link to the correct files ~~~~~~~~~~~~~~~~~~~~~~~~~ Some modules require some external files. - If you plan to use the sagemath module, you should provide a sage binary tarball that runs on the target distro (selected by the ``DISTRO`` variable) for the ``SAGE_LOCATION`` variable. You should also provide a link to a directory containing some pdf documentation for the ``SAGE_DOC_DIR`` variable. - If you plan to use the bootloader module, you should provide a file for the ``BOOTLOADER_ISO`` variable. One that works is the following slightly modified version of plopkexec.iso_. .. _plopkexec.iso: https://sagedebianlive.metelu.net/plopkexec.iso Deeper customizations ~~~~~~~~~~~~~~~~~~~~~ If, compared to what is in the existing modules, you only want to add a few Debian packages, you can do it by adding them to the ``PACKAGES`` variable in your custom config file:: PACKAGES+=' ' If you want to do something deeper, you should create your own module. For this, create a custom module, as a directory ``./modules//``. You can have a look to existing modules to get some hint on how it works. In this directory, add a file ``deploy.sh`` that contains the commands that deploys the module by tuning the config directory of the Debian Live. Some functions (which are defined in the ``macros.sh`` file) may help you in this task: - If you want to add some packages that are included in Debian, just add the line :: add_packages "" " " - If you want to add some localized packages, see for example the ``add_packages_l10n`` function used in the packages module. - If you want to add an external .deb file (be carefull to also add the required dependencies), just ad the line :: add_deb "" - If you want to add a ```` to some ```` of the booted key with ```` permissions, just add the line :: add_file_path Note that if you want to add some files to the user's directory, you should add them to the ``/etc/skel`` directory whose content will be copied to the user's homedir during the first boot of the live system. - If you want to add a ```` that belongs to your module's directory to some ```` of the booted key with ```` permissions, just add the line :: add_file_name - If you want to add a launcher to the desktop whose icon will be stored to ````, create the ``.icon.svg`` and ``.desktop`` in your module directory, and add the line :: add_launcher - If you want your module to depend on another module, just add the line :: load_module - If you want to add a hook script that will be run a root, create a file ```` (which must end with either ``.chroot`` or ``.binary`` wether you want it to be executed during the chroot or binary phase) just add the line :: add_hook - If you want to add a boot menu entry whose title is ```` that uses additional custom boot options ```` and ````, just add the line :: add_boot_menu "" " " Alternatively, you can set the ``HARDCODED_SYSLINUX_MENU`` variable to the path of a file that will be used as a ``live.cfg`` file. In both cases, you should add ``syslinux`` at the end of your modules list. Then, you can add your module by modifying the ``MODULES`` variable as follows in your ``./config/`` file:: MODULES+=' ' Of course, if your customization improves an existing module, you can modify it and push your changes. Launch the build ---------------- From the source directory, run :: ./build.sh If you use a custom ``./config/`` file to overwrite some default variables, run :: ./build.sh Note that config files can be stacked, for example you can customize an existing config by running :: ./build.sh If you want to work on your custom config that you will build a lot of time, you can use the debug config file that adds the ``root`` password to the root user (useful if you can not log in as user and still want to inspect things) and that downloads everything (even releases and security updates) from apt-cacher (do not forget to tune the ``expire_hours`` variable of ``/etc/apt-cacher/apt-cacher.conf``), run :: ./build.sh debug If you want to build a kiosk CD with french support, run :: ./build.sh kiosk fr If you want to build a kiosk CD with french and german support that still uses english as default language (the last language config overwrites the boot parameters set in the previous ones), run :: ./build.sh kiosk fr de en The image can be found in the ``BUILD_DIR`` directory, which by default is ``/var/opt/live/build/``. Test the image -------------- To test the image you built without having to burn a CD/USB, you can install the package kvm and run :: sudo qemu-system-i386 -m 1G Share your contributions ------------------------ If you think some of your customization could be of interest to someone else, please do not hesitate to share them by contacting us (you can either send your code on the mailing-list or request a pull from your public git repository).