MyLFS-big_bash_script/example_extension/README

This directory contains an example MyLFS extension.

What is a MyLFS extension?
    MyLFS by itself builds the Linux From Scratch System V Init version
almost exactly according to the book. The end result is of course very
minimal, and that's where Beyond Linux From Scratch comes in. You can use
the instructions in that book to add packages and expand on the system that
you have built. MyLFS extensions are modules that contain the information
needed to automatically build BLFS packages, on top of the LFS system that
MyLFS builds.

How to create an extension:

- Ideally create a git repository that you use to maintain your extension.
  All you really need is a directory that can be named anything.

  For example:
    my_extension/


- Inside of your repository, add a file called "packages.sh". This will contain
  a listing of the URLs of all of the packages your extension will be
  building. The format should look like this:

    ```
    # Comments and empty lines are allowed.
    # Each line should start with "export".
    # Each variable name should have either
    # a "PKG_" or a "PATCH_" prefix.

    export PKG_LYNX=<lynx tarball URL>
    export PATCH_LYNX=<lynx patch URL>

    # don't add any other code, since this
    # file is both 'sourced' and parsed by
    # mylfs.sh.
    ```


- Once you have established the list of package URLs inside of packages.sh,
  you can add the build scripts for each respective package.

    For example:
      my_extension/lynx.sh     -> builds PKG_LYNX
      my_extension/makeca.sh   -> builds PKG_MAKECA

    The script names should be the same as the package names, but lower
    case and without the "PKG_" prefix, e.g. "lynx.sh" and "PKG_LYNX".

    The contents of these scripts should contain the build instructions
    defined in BLFS for that particular package. they will be executed
    from within the unzipped package directories, just as the instructions
    from BLFS are, so they can be left unchanged.

    If a package you are building needs to be patched prior to the build,
    be sure to apply the patch yourself at the top of your script. All patches
    and tarballs will be accessible from "above" the directory where the
    script is executing.

    For example:
    ```
    # lynx.sh
    # this is running inside of the extracted
    # package tarball associated with this script.

    # patch applied here
    patch -Np1 -i ../$(basename $PATCH_LYNX)

    ./configure --prefix=/usr          \
                --sysconfdir=/etc/lynx \
                --datadir=/usr/share/doc/lynx-2.8.9rel.1 \
                --with-zlib            \
                --with-bzlib           \
                --with-ssl             \
                --with-screen=ncursesw \
                --enable-locale-charset
    make

    make install-full
    chgrp -v -R root /usr/share/doc/lynx-2.8.9rel.1/lynx_doc
    ```


- Finally, create a file called "build_order.txt" in your extension directory.
  This file should contain the list of packages to build. mylfs.sh will
  build each one in the order that they occur in this file.

    For example:
      my_extension/build_order.txt

    ```
    # Comments and empty lines are allowed.
    # The name of each item in the list should
    # be the same as the script name, but without
    # the ".sh" suffix.

    lynx
    makeca

    # if the name of a script, does not match the
    # name of the package it is building, you can
    # specify the package name in all caps like so:
    my_script  PACKAGENAME

    # this is useful if you want to build something twice
    # to get around some circular dependency.
    ```


- You can also optionally do the following:

    1. Add a directory called "static" that contains files that will be copied
       as-is into the LFS file system. The files should be named according to
       their destination path, except "/" should be replaced with "__".

       For example:
            static/home__user__.bashrc  -> will be copied to /home/user/.bashrc

       This will replace any files that already exist with the same name.


    2. Add a file called "config.sh". It can contain any code you want, but
       ideally it would provide exported variables that you can then use in
       your build scripts, or as you will see, in file templates.

       Be careful with how you name your variables. You may override some important
       environment variable that affects the behavior of the script in unexpected
       ways. Don't expect your config.sh to change the behavior of the baseline LFS
       build. Your extension's config.sh will only be sourced into the script at the
       *end* of the LFS build (which is also the beginning of the extension build).


    2. Add a directory called "templates" that contains files named in the
       same manner as those under "static", the difference being that you can
       use environment variables inside the files that will be replaced with
       their associated values at run-time.

       For example:

       ```
       # config.sh
       export MYHOSTNAME=mycoolhostname
       ...
       ```

       ```
       # templates/etc__hosts
       127.0.0.1   localhost
       127.0.1.1   $MYHOSTNAME   <-   this will be replaced with "mycoolhostname"
       ...
       ```


More Notes:

- The package tarballs for extensions will be saved to "<extension-dir>/packages/",
  separate from the LFS packages that are kept in "MyLFS/packages/". The same is true
  for the extension build logs, which will be kept in "<extension-dir>/logs/".

- mylfs.sh treats extensions as a fifth phase, ontop of the four builtin phases.
  Therefore, if you want to have the script jump straight to your extension
  scripts on an already built lfs.img, specify the following when running
  the script:

    sudo ./mylfs.sh --extend path/to/extension --start-phase 5

  Note the '--start-phase 5' bit.