Introduction to building open source software

From Foss2Serve
(Difference between revisions)
Jump to: navigation, search
m
m
 
(7 intermediate revisions by 4 users not shown)
Line 4: Line 4:
 
|'''Title''' || Introduction to building open source software
 
|'''Title''' || Introduction to building open source software
 
|-
 
|-
|'''Overview''' || In the modern UNIX/Linux/BSD era, the most common way to build and install open source software is with the use of "configure" and "make" tools. This exercise provides an introduction to building
+
|'''Overview''' || In the modern UNIX/Linux/BSD era, the most common way to build and install open source software is with the use of "configure" and "make" tools. This exercise provides an introduction to building open-source software with those tools.
open-source software with those tools.
+
 
|-  
 
|-  
 
|'''Prerequisite Knowledge''' || Students should be comfortable with: uncompressing source "tarballs", using the Linux commandline, using "su" (or "sudo") to gain root privileges, installing software packages with the native package manager
 
|'''Prerequisite Knowledge''' || Students should be comfortable with: uncompressing source "tarballs", using the Linux commandline, using "su" (or "sudo") to gain root privileges, installing software packages with the native package manager
Line 13: Line 12:
  
 
=== Background: ===
 
=== Background: ===
https://www.gnu.org/software/make/manual/html_node/Introduction.html<BR>
+
* https://www.gnu.org/software/make/manual/html_node/Introduction.html
http://airs.com/ian/configure/configure_1.html
+
* http://airs.com/ian/configure/configure_1.html
 +
* As an alternative to the below ''curl'' example, the ''htop'' project has one of the best [https://github.com/hishamhm/htop/blob/master/INSTALL build documentation files] out there, and it is a relatively simple project.
  
 
=== Directions: ===
 
=== Directions: ===
Line 25: Line 25:
 
On Fedora, in GNOME, it will look something like this:
 
On Fedora, in GNOME, it will look something like this:
  
 +
[[File:Sample-terminal.png||GNOME terminal, user in home directory]]
  
 +
==== Preparing the system ====
  
EXAMPLE CODE
+
Now, we need to make sure we have the software installed that will let us download, build, and install new software from source code. These tools are:
  
Run each statement below in a bash terminal. Then answer the questions below (or as you go).
+
* wget - a command-line tool to download files from the internet
 +
* libtool - a utility that helps to generate shared library files
 +
* make - a utility that parses Makefiles and starts the build
 +
* gcc - the GNU compiler collection
 +
* tar - a program used to make and unpack archive files
 +
* sed - a stream text editor utility that curl uses to configure
 +
* grep - a pattern matching utility that curl uses to configure
 +
* zlib - a compression library that curl detects and uses if present
  
 +
Most (if not all) of these items should already be installed on your Linux system, but we'll make sure. In order to install software packages on Linux, you will need to use root privileges. You can either use "su" or "sudo" for this. Sudo is easier, but it requires that your user be configured in /etc/sudoers first. Ask your instructor if this is the case. Su works as long as you know the root password (it will ask you for it).
 +
 +
su method:
 
  <nowiki>
 
  <nowiki>
ls
+
      su -c "yum install wget libtool gcc-c++ tar sed grep zlib-devel make -y"
touch f1
+
</nowiki>
ls
+
mv f1 f2
+
ls
+
cp f2 f1
+
ls
+
rm f2
+
ls
+
mkdir d1
+
mv f1 d1
+
ls
+
ls d1
+
pwd
+
cd d1
+
pwd
+
ls
+
cd ..
+
pwd
+
ls
+
rm d1 # fails
+
rm -r d1
+
</nowiki>
+
  
# What does `ls` display?
+
sudo method:
# What does `mv A B` do if `B` ___is not___ a directory?
+
<nowiki>
# What does `mv A B` do if `B` is a directory?
+
        sudo yum install wget libtool gcc-c++ tar sed grep zlib-devel make -y
# What does `cp A B` do if `B` ___is not___ a directory?
+
</nowiki>
# What does `rm A` do if `A` is a file?
+
# What does `mkdir A` do?
+
# What does `pwd` display?
+
# What does `ls A` display if `A` is a directory?
+
# What does `cd A` do?
+
# What does `cd ..` do?
+
# What does `..` mean in `cd ..`?
+
# When do you use `rm -r A` instead of `rm A`?
+
  
 +
Now that we have these software tools installed, we will download the source code (curl) that we're going to be using today. At the command-line of your terminal, run:
  
 +
<nowiki>
 +
        wget http://curl.haxx.se/download/curl-7.43.0.tar.bz2
 +
</nowiki>
  
==== Getting Help ====
+
This will download "curl-7.43.0.tar.bz2" into your home directory. Next, unpack this source archive (also called a "tarball") using the tar command:
  
Run each statement below in a bash terminal. Then answer the questions below (or as you go).
+
<nowiki>
 +
        tar xvf curl-7.43.0.tar.bz2
 +
</nowiki>
 +
 
 +
The options to the tar command are:
 +
* x - eXtract
 +
* v - Verbose (show us what is happening)
 +
* f - File (we're working with a file. tar started life a long time ago writing to tape drives for backups, so we have to tell it we're working on modern files instead)
 +
 
 +
You should see a lot of files scroll by, and end up with a "curl-7.43.0" directory. Go into that directory:
  
 
  <nowiki>
 
  <nowiki>
man
+
        cd curl-7.43.0
man man # Press `space` to page down, `b` to go back, `q` to quit.
+
</nowiki>
man ls
+
 
man cd # Unexpected result.
+
Answer these questions:
help cd
+
 
</nowiki>
+
# What did the `yum` command do?
 +
# Why did we need to use `su` or `sudo` to install packages?
 +
# What is a "tarball"? How can we tell if a file is a "tarball"?
 +
 
 +
==== Configuring and Building Source Code ====
 +
 
 +
Look at the files in the curl-7.43.0 directory with the `ls` command. This is the top-level of the source code tree for curl. There are a few files you should know about:
 +
 
 +
* configure - This is the script that you will run to configure the curl source code to be built on your Linux system. Sometimes, configure needs to be generated from configure.ac (using a tool called `autoconf`), but this curl source tree already has a valid `configure` script.
 +
* configure.ac - This is the raw source file that is used to make the `configure` script. You will not need to touch it now, but you should open it in a text editor and compare it to the contents of `configure`.
 +
* Makefile - This is the file that tells `make` how to build the code. It is generated from Makefile.in by the `configure` script. Curl comes with a preconfigured `Makefile`, but `configure` will replace it.
 +
* Makefile.in - This is the source file that is used to make the `Makefile`. Open it in a text editor and compare it to the contents of `Makefile`.
 +
 
 +
TODO -finish
 +
 
 +
Answer these questions:
 +
# What utility generated `Makefile.in`?
 +
 
 +
==== Installing the code ====
 +
TODO
  
# What does `man` do?
+
Answer these questions:
# What does `help` do?
+
# TODO
# Use `man` to confirm answers in previous section.
+
  
 
=== Deliverables: ===
 
=== Deliverables: ===
# Answers and explanations for the license scenarios
+
# Answers and explanations for the questions in each section.
# A short lightning talk presentation that clearly illustrates a correct and attributed use of CC materials.
+
# curl should successfully be installed in /opt/curl
  
 
=== Assessment: ===
 
=== Assessment: ===
Students can be graded on choosing a correct license, understanding how a license affects what can be done with a creative work, and on their ability to put that knowledge into practice.
+
Students can be graded on understanding the build & install process, as well as successful build and installation of curl from source code.
 
{| border="1"
 
{| border="1"
 
|-  
 
|-  
 
|'''Criteria''' ||'''Level 1 (fail)'''||'''Level 2 (pass)'''||'''Level 3 (good)'''||'''Level 4 (exceptional)'''  
 
|'''Criteria''' ||'''Level 1 (fail)'''||'''Level 2 (pass)'''||'''Level 3 (good)'''||'''Level 4 (exceptional)'''  
 
|-
 
|-
|Choosing a correct CC license || 0-2 correct answers || 2-4 answers correct, with valid reasoning  (or more answers correct, but without valid reasoning) || 4-5 answers correct, with valid reasoning || All answers correct, with valid reasoning.       
+
|Understanding the build & install process || 0-3 correct answers || 3-6 correct answers || 6-9 answers correct || All answers correct, with valid reasoning.       
 
|-
 
|-
|Understanding how a license affects what can be done with a creative work || 0-1 correct answers || 1-2 correct answers || 2-3 correct answers || All answers correct
+
|Successful build and installation of curl from source code || Code not built or installed || Student attempted to build, but could not install || Student built code, but did not install correctly into /opt/curl || Code is built and installed correctly into /opt/curl 
|-
+
|Presentation || Does not attribute sources at all || Lists license but not full attribution || Contains proper attributions, but only a few sources. || Multiple sources, properly attributed. Talk itself is properly CC licensed   
+
 
|-
 
|-
 
|}
 
|}
Line 143: Line 155:
 
[[Category: Learning_Activity]]
 
[[Category: Learning_Activity]]
 
[[Category:Coding_and_Style]]
 
[[Category:Coding_and_Style]]
 +
 +
[[Category: CS2]]
 +
 +
[[Category: Good_Draft]]

Latest revision as of 16:07, 22 April 2017

Title Introduction to building open source software
Overview In the modern UNIX/Linux/BSD era, the most common way to build and install open source software is with the use of "configure" and "make" tools. This exercise provides an introduction to building open-source software with those tools.
Prerequisite Knowledge Students should be comfortable with: uncompressing source "tarballs", using the Linux commandline, using "su" (or "sudo") to gain root privileges, installing software packages with the native package manager
Learning Objectives Student should be able to configure, build, and install software using the "configure" and "make" tools.

Background:

Directions:

First, let's get started by opening a terminal window. You should be logged in as your normal (non-root) user. If you are not in your home directory, go there by typing:

        cd ~

On Fedora, in GNOME, it will look something like this:

GNOME terminal, user in home directory

Preparing the system

Now, we need to make sure we have the software installed that will let us download, build, and install new software from source code. These tools are:

  • wget - a command-line tool to download files from the internet
  • libtool - a utility that helps to generate shared library files
  • make - a utility that parses Makefiles and starts the build
  • gcc - the GNU compiler collection
  • tar - a program used to make and unpack archive files
  • sed - a stream text editor utility that curl uses to configure
  • grep - a pattern matching utility that curl uses to configure
  • zlib - a compression library that curl detects and uses if present

Most (if not all) of these items should already be installed on your Linux system, but we'll make sure. In order to install software packages on Linux, you will need to use root privileges. You can either use "su" or "sudo" for this. Sudo is easier, but it requires that your user be configured in /etc/sudoers first. Ask your instructor if this is the case. Su works as long as you know the root password (it will ask you for it).

su method:

       su -c "yum install wget libtool gcc-c++ tar sed grep zlib-devel make -y"
 
sudo method:

        sudo yum install wget libtool gcc-c++ tar sed grep zlib-devel make -y
 

Now that we have these software tools installed, we will download the source code (curl) that we're going to be using today. At the command-line of your terminal, run:

        wget http://curl.haxx.se/download/curl-7.43.0.tar.bz2
 

This will download "curl-7.43.0.tar.bz2" into your home directory. Next, unpack this source archive (also called a "tarball") using the tar command:

        tar xvf curl-7.43.0.tar.bz2
 

The options to the tar command are:

  • x - eXtract
  • v - Verbose (show us what is happening)
  • f - File (we're working with a file. tar started life a long time ago writing to tape drives for backups, so we have to tell it we're working on modern files instead)

You should see a lot of files scroll by, and end up with a "curl-7.43.0" directory. Go into that directory:

        cd curl-7.43.0
 

Answer these questions:

  1. What did the `yum` command do?
  2. Why did we need to use `su` or `sudo` to install packages?
  3. What is a "tarball"? How can we tell if a file is a "tarball"?

Configuring and Building Source Code

Look at the files in the curl-7.43.0 directory with the `ls` command. This is the top-level of the source code tree for curl. There are a few files you should know about:

  • configure - This is the script that you will run to configure the curl source code to be built on your Linux system. Sometimes, configure needs to be generated from configure.ac (using a tool called `autoconf`), but this curl source tree already has a valid `configure` script.
  • configure.ac - This is the raw source file that is used to make the `configure` script. You will not need to touch it now, but you should open it in a text editor and compare it to the contents of `configure`.
  • Makefile - This is the file that tells `make` how to build the code. It is generated from Makefile.in by the `configure` script. Curl comes with a preconfigured `Makefile`, but `configure` will replace it.
  • Makefile.in - This is the source file that is used to make the `Makefile`. Open it in a text editor and compare it to the contents of `Makefile`.

TODO -finish

Answer these questions:

  1. What utility generated `Makefile.in`?

Installing the code

TODO

Answer these questions:

  1. TODO

Deliverables:

  1. Answers and explanations for the questions in each section.
  2. curl should successfully be installed in /opt/curl

Assessment:

Students can be graded on understanding the build & install process, as well as successful build and installation of curl from source code.

Criteria Level 1 (fail) Level 2 (pass) Level 3 (good) Level 4 (exceptional)
Understanding the build & install process 0-3 correct answers 3-6 correct answers 6-9 answers correct All answers correct, with valid reasoning.
Successful build and installation of curl from source code Code not built or installed Student attempted to build, but could not install Student built code, but did not install correctly into /opt/curl Code is built and installed correctly into /opt/curl

Comments:

What should the instructor know before using this activity?

A basic familiarity with autotools generated configure and Makefiles is very helpful, though, not necessarily required.

Additional Information:

Knowledge Area/Knowledge Unit Software Engineering (SE) / Tools and Environments
Topic Software configuration management and version control
Level of Difficulty Easy
Estimated Time to Completion 30 minutes to 1 hour
Materials/Environment Internet access, computer (or VM) with Linux installed, student has account and root access (sudo is fine). Some commands reference Fedora, but can be converted to other Linux flavors.
Author Tom Callaway
Source
License This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License


Suggestions for the Open Source Project:

What documentation do you provide on how to build your code? Is it current and accurate? Do you discuss the various configuration options and what effect they have on the final build?



This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

CC license.png

Personal tools
Namespaces
Variants
Actions
Events
Learning Resources
HFOSS Projects
Evaluation
Navigation
Toolbox