From 846b87b954cb3ac8b81251d28deeb3cb5988d33c Mon Sep 17 00:00:00 2001 From: "A. Wilcox" Date: Sun, 24 Sep 2017 21:25:01 -0500 Subject: Developer guide: fill in chap2 and 3, add Makefile --- src/devel/1_preparing.xml | 260 ++++++++++++++++++++++++++++++++++++++++++++++ src/devel/2_nonpkg.xml | 31 ++++++ src/devel/3_git.xml | 104 +++++++++++++++++++ src/devel/4_hello.xml | 9 ++ src/devel/5_deepdive.xml | 9 ++ src/devel/6_security.xml | 9 ++ src/devel/7_misc.xml | 9 ++ src/devel/8_help.xml | 9 ++ src/devel/develguide.xml | 38 +++++++ 9 files changed, 478 insertions(+) create mode 100644 src/devel/1_preparing.xml create mode 100644 src/devel/2_nonpkg.xml create mode 100644 src/devel/3_git.xml create mode 100644 src/devel/4_hello.xml create mode 100644 src/devel/5_deepdive.xml create mode 100644 src/devel/6_security.xml create mode 100644 src/devel/7_misc.xml create mode 100644 src/devel/8_help.xml create mode 100644 src/devel/develguide.xml (limited to 'src/devel') diff --git a/src/devel/1_preparing.xml b/src/devel/1_preparing.xml new file mode 100644 index 0000000..0966a44 --- /dev/null +++ b/src/devel/1_preparing.xml @@ -0,0 +1,260 @@ + + + Preparing Your System + Welcome to the Adélie Linux 1.0 Developer's Guide. This guide will teach you how to develop the software and packages that powers the Adélie Linux distribution. You may follow along at your own pace. + We'll start with installing the software and writing the configuration files necessary to perform development. +
+ Installing Development Software + In this section, you will learn: + + How to install software on Adélie Linux; + What software you will use to develop Adélie Linux; and + What task each utility in the Adélie Linux development system performs. + + Please make sure that you are at an Adélie Linux terminal before continuing. +
+ Using <command>apk</command> to Install Software + The Alpine Package Keeper or apk package manager is the central software management tool on the Adélie Linux distribution. + For a more thorough introduction to the apk package manager, please consult the Adélie Linux 1.0 Administrator's Guide, chapter 3: "Packages". + The apk package manager automatically resolves dependencies for requested software packages, and will automatically remove or "clean up" unneeded dependencies when a software package is removed. + If a software package's files become corrupted, it can be reinstalled with the fix subcommand. + The add subcommand will add the specified package(s) to the system's list of packages, and then resolve all necessary dependent libraries and other software packages to ensure the system has the requested packages installed. + The del subcommand will remove the specified package(s) from the system's list of packages, and then remove any other libraries and software packages that are no longer required for the system's operation. For example, the command: + # apk add build-tools + will install the build-tools package, and any packages and libraries it requires. Similarly, + # apk del libressl-dev + will remove the libressl-dev package, and any packages and libraries that it required and no other package on the system requires. +
+
+ Installing the Adélie Linux Development System + The development environment is made of two essential parts: the build-tools package, which provides the basic compiler infrastructure, including a C compiler, build system, linker, assembler, and other utilities; and the abuild package, which takes package "recipe" files with build instructions, and creates the APK package files using them. You may install these two packages by executing the following command: + # apk add abuild build-tools +
+
+ Components of the Adélie Linux Development System + The development system uses many open-source technologies that work together to provide a responsive, cohesive, libre environment. + + Development System Components + + abuild (abuild) + Builds APK package files from APKBUILD package "recipe" files. + + + autoconf (autoconf) + The GNU package for generating ./configure scripts in packages that require them to be generated. + + + automake (automake) + The GNU package for generating Makefiles in packages that use the autoconf package. + + + attr + A framework for ACLs or access control lists. + + + bash (bash, sh) + A Unix shell mostly compliant with the POSIX standard, used by many packages for build scripts and testing. + + + binutils (as, ld, nm, …) + Low-level development utilities including assembler (as), linker (ld), and others. + + + bison (yacc) + The GNU version of the yacc compiler generation command. + + + bzip2 (bzip2, bunzip2, bzless, …) + A popular compression format, included for the ability to unpack .bz2 archives within which packages may be distributed. + + + cmake (cmake, ctest) + The CMake build system, used to build many packages, and the CTest test system, used to prove packages are functioning correctly on the local system. + + + diffutils (diff, cmp) + Compares two or more files together, showing the differences. Used by many test suites, and also useful for troubleshooting and generating .patch files. + + + fakeroot + An environment where a package believes it is running as the root user, but is actually running as the build user. + + + flex (lex) + The GNU version of the lex lexer, used for creating parsers in many projects. + + + gcc (c99, c11, gcc, g++) + The GNU Compiler Collection, a mostly standards-compliant C and C++ compiler. + + + git (git) + A distributed version control system used by many projects to keep a record of file history; the current distribution method for Adélie's package repository. + + + gzip (gzip, gunzip) + A popular, long-standing compression format, included for the ability to unpack .gz archives within which packages may be distributed. + + + libarchive (cpio, tar) + tar allows creation of APK files and extraction of a popular archive format; cpio is used to create the initial boot disk for CD images. + + + libtool (libtool) + The GNU library manipulation tool, used by many packages to create shared (.so) and static (.a) library files. + + + lzip (lzip) + A compression format, included for the ability to unpack .lz archives within which packages may be distributed. + + + make (make) + The GNU version of the standard Unix make command. + + + mawk (awk) + A POSIX compliant implementation of the AWK programming language. + + + openssl (openssl) + A command to sign packages cryptographically, ensuring they are not tampered with when a user downloads them. + + + patch (patch) + The GNU version of LarryWall's standard patchutility. + + + pax-utils (dumpelf, symtree) + A collection of utilities to enable the building of packages for the PaX secure operating environment. + + + pkgconf (pkgconf, pkg-config) + A freely licensed, mathematically proven pkg-config implementation, used by package build systems to determine the location of libraries on the system. + + + sed (sed) + The GNU version of the Unix sed command. + + + sudo (sudo) + Allows a user to run a command as the root user without using the root user's password. + + + xz (xz, unxz) + An efficient compression format, included for the ability to unpack .xz archives within which packages may be distributed. + + +
+
+
+ Packaging Primer + In this section, you will learn: + + How repositories and packages work in the Adélie Linux distribution; + How to use the abuild command; and + The options and commands available in abuild. + +
+ Packages and Repositories + The abuild command enables you to build a package file for later installation on to one or more computers running the Adélie Linux dsitribution. A package file is a kind of archive file that contains two key parts: package metadata, and package content files. + Package metadata is a collection of information used by a package manager, such as apk, to determine information about the package and the package file, including its name, version, maintainer contact information, installed size on disk, and more. The package content files are a collection of one or more files that comprise the package itself, including executables, default configuration, data files, and any other files needed for the package to work properly. In some cases it may also include templates, examples, or documentation. + All packages belong to a package repository or repo. A repository is a collection of related packages. The Adélie Linux distribution has three main repositories: the system repository, used for system software and important libraries; the user repository, used for the majority of packages that users may be interested in; and the nonfree repository, containing packages that do not have a free or libre license. + While you are developing on your own computer, you may have as many, or as few, repositories as you like. It can use any name except the above three. You may use a name such as mypackages, or just your username. The repository is a directory on your computer's hard disk. You may create it anywhere, but it is highly recommended that you store your repository in your home directory (/home/yourname). + Each package you create will have its own directory inside your repository. If you use the newapkbuild command (discussed later), this will be created for you automatically. Inside this directory will be at least an APKBUILD file, which tells abuild the commands to run to build the package. It may also contain patches or other files necessary for building the package, if necessary. + Typically, the abuild command is executed inside the package's directory (for example, /home/yourname/packages/pkgname). However, by setting the APKBUILD environment variable to the absolute path on disk to an APKBUILD file, you may run abuild from any directory. +
+
+ Using the <command>abuild</command> Command + Running the abuild command with no arguments in a directory containing an APKBUILD file will cause it to install the dependencies of the package as listed in the APKBUILD, and then build the package. Afterwards, the dependencies of the package that were not already installed on your computer are removed. + If the build concluded successfully, the directory tree created for the source code and build system are removed by default. You may configure what abuild removes when a package concludes building. + If the build fails to conclude successfully, no directories are removed by default. You may configure what abuild removes when a package fails to build. + abuild has many commands that you may use, for finer-grained control over the build process. You may use the abuild deps command to only install the dependencies of the package, and use the abuild unpack command to unpack the source archive into the directory tree where it can later be built. These and many other commands are described in more detail in the following section. + There are additionally a number of options that you may pass to abuild, which are also described in more detail in the next section. +
+
+ <command>abuild</command> Commands + +
+
+
+ Configuring Your System + In this section, you will learn: + + How to configure abuild for your environment; + How to create and use package signing keys; and + The directory layout used by abuild and how to create it. + + Please make sure that you are at an Adélie Linux terminal before continuing. +
+ Configuring <command>abuild</command> for Your Environment + The abuild system reads its configuration from two files on your system, if they exist. + The /etc/abuild.conf file contains system-wide configuration, used by all users on a system. + The $HOME/.abuild/abuild.conf contains user-specific configuration, including the packager name and key pair path. This allows multiple users to create their own repositories on a single system. + Configuration set in the /etc/abuild.conf will apply to all packages on the system unless overridden by the user-specific configuration file. + The most common configuration variables are explained below. For a list of all available configuration variables, consult the abuild.conf(5) manual page by running man 5 abuild.conf on a computer where the abuild-doc package is installed. + + <filename>abuild.conf</filename> Configuration Variables + + CFLAGS + CFLAGS contains the flags passed to the C compiler. For more information about available flags, consult the documentation for your compiler. + + + CXXFLAGS + CXXFLAGS contains the flags passed to the C++ compiler. If CXXFLAGS is not set, and CFLAGS is set, then CXXFLAGS is set to the value of CFLAGS. + + + CPPFLAGS + CPPFLAGS contains the flags passed to the C and C++ preprocessors. + + + LDFLAGS + LDFLAGS contains the flags passed to the linker. For more information about available flags, consult the documentation for your toolchain (likely binutils). + + + JOBS + JOBS should be set to the number of concurrent build processes you would like to run on your system. Most dedicated build servers use a number equal to the number of CPU cores. + + + MAKEFLAGS + MAKEFLAGS contains the flags passed to make. The default value is -j$JOBS. For more information about available flags, consult the documentation for make. + + + USE_COLORS + USE_COLORS controls whether or not the abuild command will output colours to the terminal. If you prefer a colourless output, or your terminal is not capable of ANSI colour codes, set this to 0. The default value is 1. + + + SRCDEST + SRCDEST should be an absolute path where source files are downloaded. The default, and typical, value is /var/cache/distfiles. + + + REPODEST + REPODEST should be an absolute path where finished packages are placed when built. The default is $HOME/packages/. + + + PACKAGER + The value of PACKAGER is added to every produced package as the person responsible for packaging it. Typically, this follows an RFC822-style "Name <Email Address>" format. There is no default value; it must be set before running abuild. + + + PACKAGER_PRIVKEY + PACKAGER_PRIVKEY should be an absolute path to the packager's private key, which will be used to sign every produced package. Typically, this is set for you by the abuild-keygen command. There is no default value; it must be set before running abuild. + + + MAINTAINER + The value of MAINTAINER is used as a point of contact if a user has an issue with a package, or if a security patch or update is available for the patch. Typically, this follows an RFC822-style "Name <Email Address>" format. The default value is the value of PACKAGER. + + + CLEANUP + CLEANUP controls the cleanup procedure after a build that concludes with success. The default value is srcdir pkgdir deps. + + + ERROR_CLEANUP + ERROR_CLEANUP controls the cleanup procedure after a build that concludes with failure. The default value is deps. + + + DEFAULT_DBG + DEFAULT_DBG controls whether a debug package will be created for compiled packages. It is unset by default; being set to any value enables the option. The typical value to enable the option is YesPlease. + + +
+
+ diff --git a/src/devel/2_nonpkg.xml b/src/devel/2_nonpkg.xml new file mode 100644 index 0000000..c844be9 --- /dev/null +++ b/src/devel/2_nonpkg.xml @@ -0,0 +1,31 @@ + + + Non-Package Development + There are a number of ways to contribute to the development of Adélie Linux that do not involve packaging. This chapter will introduce you to other Adélie Linux projects and how to set up a development environment for each one. +
+ Developing Adélie Documentation + In this section, you will learn: + + How documentation and guides like this one are authored; and + How you can configure your environment to edit and author documentation for Adélie Linux. + +
+ Authorship of Documentation + The Adélie Linux Documentation Set, including the guide that you are reading, is written in a format called DocBook. DocBook is somewhat similar to HTML in that it uses tags to define the semantics of the document, but the tags DocBook uses are different from HTML's and focus on creation of books and manuals. + The main Documentation Set is written in English, but we are happy to accept translations of our documentation into other languages. + You can contribute corrections, additions, or translations of any portion of our documentation by emailing the adelie-docs mailing list with your patch, or by creating a merge request on the Documentation GitLab page. For more information about using Git to create patches and merge requests, see chapter 3. +
+
+ Configuring Your Environment + You will need to install the xmlto package to ensure your changes leave the documentation syntatically valid. After making your changes, run the xmlto command on the primary file (for this guide, develguide.xml) and ensure there are no errors. +
+
+
+ Spread the Word + There are many ways to spread the word about Adélie Linux. + Talk to your friends about Adélie Linux and the benefits of libre software, including security, speed, and less need to purchase new computers every year. + Have civil discussions on forums, newsgroups, and social media. + If you're a student, talk to your school's Computer Science department and see if they are interested in a lab with Adélie Linux. + By spreading the word, you're helping more people learn and spreading our ideas and goals worldwide. Thank you! +
+ diff --git a/src/devel/3_git.xml b/src/devel/3_git.xml new file mode 100644 index 0000000..ed97eca --- /dev/null +++ b/src/devel/3_git.xml @@ -0,0 +1,104 @@ + + + Git Basics + The majority of Adélie Linux projects are stored in a distributed version control system called Git. + In this chapter, we will see an overview of how Git works, find out where its documentation lives, and learn about Adélie-specific workflows in Git. +
+ Getting Started with Git + In this section, you will learn: + + What Git and distributed version control systems provide; + How to configure Git for work on Adélie Linux projects; and + Where to find documentation about Git. + +
+ What is Git? + A version control system is a system that keeps track of a collection of related files, called a repository, and how they change over time. + If you are familiar with Mac OS X's Time Machine functionality, a version control system is similar to this; it keeps a record of each file, when it was changed, and who changed it. + The primary difference is that a version control system only saves records of files when you explicitly tell it to do so. This saving of a record is called a commit, and the list of all commits is called a commit log. + A distributed version control system allows many people to have their own copies of the repository containing the full commit log. When a person wants to provide their commits to others, they push their commits to a central server. + Typically, people work on their own branch, or private tree of files. When a person pushes their changed branch to the central server, it allows them to merge other branches. + Git is a distributed version control system that runs on many different kinds of computers, and is very popular in open source development. The Adélie Linux distribution uses Git to track everything from the package repositories, to the documentation set, to libraries and other software written for Adélie Linux. + Git allows us to maintain a record of who has contributed to the project, the date they contributed, and what changes they contributed. It is therefore very important that you configure Git on your system to have your name and email address, so that the commit log attributes you correctly. +
+
+ Configuring Git + If you have not already done so, you must first provide your name and email address to Git. You may do this by running the following two commands: + $ git config --global user.name "Your Name" + $ git config --global user.email "email@address.tld" + If you have a PGP key (used for signing electronic messages), and it is publicly known and cross-signed, you should additionally provide this to Git. This will allow more provability that you are the one who created a commit. You may do this by running the following two commands: + $ git config --global user.signingkey YourPublicKeyFingerprint + $ git config --global commit.gpgsign true +
+
+ Learning More about Git + There are many helpful resources available for you to learn more about Git. + You may install the git-doc package on your Adélie computer for easy access to the built-in manuals. + Additionally, if you have access to the World Wide Web, you may read the freely-licensed Pro Git book at https://git-scm.com/book/en/v2. + There are also a number of mailing lists for starting out and working with Git. +
+
+
+ Using Git with Adélie + In this section, you will learn: + + How the Adélie Linux distribution uses Git branches and commits; + How to write a good, informative commit message; and + A guideline on how frequently to make commits and merge requests. + +
+ Using Branches + A branch is a self-contained copy of a project's files. Using branches allow your changes to be reviewed quickly and, if approved, merged in to the Adélie Linux source quickly. + A branch should be a single "unit of work". That is, a branch should have a single goal in mind. Sometimes a branch can contain many commits; for instance, your goal may be "update the Gnome Office packages". In that case, you would have at least one commit for each Gnome Office package. + However, sometimes a branch only needs one commit. This can be useful for simple bug fixes, or bumping a single package's version. + Branches should have a name that reflects their goal. A branch name such as bugfix or version is unclear and doesn't communicate the goal of the branch. A branch name such as gnumeric-1.12.35-update or fix-boot-on-g3 is clear and concisely states the branch goal. + If you are not currently an Adélie Linux developer, you will create the branches in your fork, which is a private copy of the repository that is owned by you. If you are an Adélie Linux developer, you can create the branch in your own private fork or the main repository. For more information about creating forks, see the GitLab documentation. +
+
+ Commits + A commit message should have the following structure: + + + + + + + + + area: summary of change + +Multi-line details of change, if necessary. + +Signed-off-by: Your Name <email@address.tld> +Acked-by: Developer Name <email@adelielinux.org> + + + + The area changed by the commit. For source code, this is typically the module name (such as string or gnulib). For packages, this is the full name of the package, such as user/dejagnu. + + + A brief summary of the commit. The summary line should be less than 60 characters, and be a concise summary of the change made. + + + A detailed summary of the commit. You may expand on the rationale for the commit, or provide more information than you could in the summary line. + + + If you are not yet an Adélie Linux developer, use the --signoff parameter to git to reflect that you agree to the contribution guidelines of the repository. + + + If you communicated with an Adélie Linux developer about this change before sending the commit, add the Acked-by line to reflect such. This will make it easier for further review to continue. + + + + There are a few different standards for how often you should commit your work, depending on the repository to which you are contributing. + Some repositories contain guidelines in their Contribution Guide, found in the CONTRIBUTING.rst file in the root of the repository. + As a general guideline, when you are working on a source code repository, each commit should be one "logical change". + This could be adding a new function to an API, or changing an algorithm and ensuring all other files have the updated algorithm. + Similarly, when you are working on a package repository, you should use one commit per package that you change. + For instance, if you "bump" or update the version of three packages, you would use one commit for each of the three packages, for a total of three commits. + This allows an Adélie Linux developer to review each package's change separately. + There are some reasons you may want a single commit to hold changes to multiple packages. + For example, if you are updating the license fields of many packages, you may want a single commit with a message similar to main/libx*: update licenses on X11 libraries. +
+
+ diff --git a/src/devel/4_hello.xml b/src/devel/4_hello.xml new file mode 100644 index 0000000..cc45af6 --- /dev/null +++ b/src/devel/4_hello.xml @@ -0,0 +1,9 @@ + + + Writing Your First Package + +
+ + +
+ diff --git a/src/devel/5_deepdive.xml b/src/devel/5_deepdive.xml new file mode 100644 index 0000000..a0eac6b --- /dev/null +++ b/src/devel/5_deepdive.xml @@ -0,0 +1,9 @@ + + + Deep Dive in to <filename>APKBUILD</filename> + +
+ + +
+ diff --git a/src/devel/6_security.xml b/src/devel/6_security.xml new file mode 100644 index 0000000..95008c0 --- /dev/null +++ b/src/devel/6_security.xml @@ -0,0 +1,9 @@ + + + Ensuring Security + +
+ + +
+ diff --git a/src/devel/7_misc.xml b/src/devel/7_misc.xml new file mode 100644 index 0000000..f806ab7 --- /dev/null +++ b/src/devel/7_misc.xml @@ -0,0 +1,9 @@ + + + Odds and Ends + +
+ + +
+ diff --git a/src/devel/8_help.xml b/src/devel/8_help.xml new file mode 100644 index 0000000..4f43069 --- /dev/null +++ b/src/devel/8_help.xml @@ -0,0 +1,9 @@ + + + If You Need Help + +
+ + +
+ diff --git a/src/devel/develguide.xml b/src/devel/develguide.xml new file mode 100644 index 0000000..8447c80 --- /dev/null +++ b/src/devel/develguide.xml @@ -0,0 +1,38 @@ + + + + + + + + + +]> + + + Adélie Linux 1.0 Developer's Guide + + A.Wilcox + + 2017Adélie Linux + + + Preface + This Developer's Guide is the official guide to developing the Adélie Linux 1.0 system. It is designed for developers interested in working on the distribution itself; for general information on programming your computer running the Adélie Linux system, see the User's Guide chapter "Getting started with programming". + Many contributed to the final version of this guide. This includes NatanaelCopa and TimoTeras from Alpine Linux. + It is assumed that you, the reader, are familiar with using a terminal or command line interface, the use of Unix commands, and the compilation of software. If you are not yet familiar with these concepts, start with our User's Guide, which will assist you in learning them. + Please also ensure that you are comfortable and properly rested before reading this guide. This will allow you to learn quicker, and be able to recall the information you have learned easier. + It is hoped by the author that you find this guide easy to understand and read. Please feel free to contact me or the Adélie Linux community if you have any suggestions on how to make this guide better. We'd love to hear from you, and we hope you enjoy using our distribution. + – A. Wilcox, 2017 + + &chap1; + &chap2; + &chap3; + &chap4; + &chap5; + &chap6; + &chap7; + &chap8; + -- cgit v1.2.3-60-g2f50