Code on a laptop screen
MchlSkhrv/Shutterstock

Have you been told to “clone the repo and build it,” and don’t know what to do next? We’ll show you how to get that program on GitHub running on Linux, even if you’re a beginner.

The instructions that make up a computer program are written, edited, and saved in text files. A program called a compiler then processes these files. This produces the executable version of the program. The text files of instructions are called the source code. The version of the program that can actually run on a computer is called the binary or the executable.

That’s a simplified version of events, but it paints a correct—if generalized—picture. In practice, you’ll find all sorts of variations on that model. Sometimes, other programs generate the text files. Other times, the source code runs inside an interpreter and doesn’t need to be compiled, and so on.

However, the one universal truth across all software projects is this: the source code files are the crown jewels, and they need to be looked after just as carefully.

Version Control Programs

All of the source code files within a project are called the codebase. Large projects often have many developers working on the codebase. Every code change must be tracked and identifiable. If required, the changes must be reversible. If different developers make changes to the same source code file, their edits must be merged.

It’s not surprising, then, that software programs called version control systems exist to make the management of changes to the codebase easier. Version control systems hold all previous versions of each file in the codebase, and every change is recorded, commented on, and tracked.

A Little Thing Called Git

Linus Torvalds, the creator of the Linux kernel, developed a version control program called Git to administer the Linux kernel codebase. It’s now the world’s most widely adopted version control software. There are millions of people using it—literally.

With Git, a project’s codebase is stored in repositories. In addition to the local repositories that sit on developer’s computers and, perhaps, on a central server on the network, it’s a good practice to have an off-site, or remote, repository.

And that’s where GitHub comes in.

GitHub

GitHub was created as a result of git‘s success. The founders saw the emerging need for securely hosted remote git repositories. They launched a business providing a cloud platform to allow development teams to host remote repositories. As of April 2019, GitHub hosts over 100 million repositories.

If an application is an open-source project, the chances are very high that it will be hosted on GitHub. There are other repository platforms available, such as BitBucket and GitLab, but GitHub has the lion’s share of open source repositories.

Anatomy of a Repository

A GitHub repository is comprised of folders containing files such as the all-important source code files. Usually, there are many other types of files in the repository. There might be documentation files, man pages, software license files, build instructions and shell script files. There are no rules regarding what a repository should or must contain, but there are conventions.

If you know your way around one kitchen, you can navigate any kitchen. It’s the same with repositories. Once you understand the conventions, you know where to go to find what you need.

So, how do you get a copy of the repository on your computer, and how do you build the program into a binary executable?

The readme File

It’s traditional to include a readme file in a repository. It might be called readme, Readme, or README. It might have an extension of “.md” or no extension at all.

Let’s have a look at the GitHub repository for the Atom editor. You see a long list of folders and files. Scroll down, and you see the contents of the README.md file.

GitHub automatically puts the contents of the readme file on the front page of the repository. If the readme file has a “.md” extension, it will contain Markdown markup language. This allows the developers to use style elements, such as fonts, bullet points, and images.

Section of the readme.md file for the atom editor on github.

Typically, a readme file has sections that tell you what the project is about, what the type license is, who maintains the project, how to get involved, and how to build and run the application.

If it doesn’t list the actual build instructions, it will tell you where to find this information. Other information useful to building the application, such as the build tools required and other dependencies, might be listed here or a link might take you to that information.

The boxes Repository

Our mission is to clone the boxes repository, and then build the boxes application.

The repository follows the same layout the Atom one did. There’s a list of folders and files and below that is the contents of the readme file. It follows the standard layout for a repository, but it’s a smaller project, so there are fewer folders and files.

The readme file is briefer too. It has a section called “Development.” In that section is a link entitled “building from source.” If we follow that link, we should find the information we need.

Link to the build instructions for the boxes application.

There’s usually some lightweight sleuthing necessary to navigate the repository and find the information you want, but it’s not difficult. Read everything on the repository page carefully. Sometimes, the information is there but might not be prominently displayed.

The Dependencies

The “Building from Source” page has a section called “Building on Linux,” and that’s just what we need. It says we must have a C compiler, Bison, and Flex installed.

Required tool set for building the boxes application

The build instructions say to issue the make command, so we’ll also need make.

The tools required to build this application are a C compiler, Bison, Flex, make, and Git (to clone the repository to your computer).

This article was researched on computers running the Ubuntu, Fedora, and Manjaro Linux distributions. None of the distribution had all of these tools installed—something had to be installed on each of them.

Installing the Tool Set

Ubuntu had to have Git, Flex, Bison, and make installed. Here are the commands:

sudo apt-get install git

"sudo apt-get install git" in a terminal window.

sudo apt-get install flex

"sudo apt-get install flex" in a terminal window.

sudo apt-get install bison

"sudo apt-get install bison" in a terminal window.

sudo apt-get install make

"sudo apt-get install make" in a terminal window.

Fedora had to have Flex, Bison, and make installed. Here are the commands:

sudo dnf install flex

"sudo dnf install flex" in a terminal window

sudo dnf install bison

"sudo dnf install bison" in a terminal window.

sudo dnf install make

"sudo dnf install make" in a terminal window.

Manjaro had to have the GCC compiler, Flex, and Bison installed. Here are the commands:

sudo pacman -Syu gcc

"sudo pacman -Syu gcc" in a terminal window.

sudo pacman -Syu flex

"sudo pacman -Syu flex" in a terminal window.

sudo pacman -Syu bison

"sudo pacman -Syu bison" in a terminal window.

Cloning the Repository

Each GitHub repository has a specific web address used with Git to clone the repository to your computer. On the main page of the boxes repository, there’s a green button labeled “Clone or download.”

The "Clone or Download" button in GitHub.

Click the button to see the web address. This is the address we must pass to the git command when we clone the repository.

Change into the directory that we want to have the repository cloned into, and then use this command. If your terminal window supports it, you can copy and paste the web address into the command. Press Ctrl+Shift+V to paste into a GNOME terminal window.

"git clone https://github.com/ascii-boxes/boxes.git" in a terminal window.

Git clones the remote repository and creates a local one on your computer. It tells us it’s cloning into a directory called “boxes.”

Cloned repository in a terminal window.

The boxes directory is created within the directory from which you issued the git command. If we switch to the boxes directory and look at the contents, we see the same list of files and folders we saw on the GitHub page.

The boxes repository contents in a terminal window.

Great! We’ve successfully cloned the source code and other files to our computer. Now, we need to build the application.

Building the Application

To build the application, we must follow the instructions on the GitHub repository. Sometimes, we’ll run a particular shell file, and others we’ll run  make.  The build instructions we’re following told us to run make.

The make utility reads and performs a set of instructions from a makefile. These instructions tell make how to compile the program and link it together. make passes the instructions to the compiler and other build tools.

The command we’re told to use will call make twice. The first call to make builds the application, and the second runs a suite of tests.

The command the build instructions told us to use is:

make && make test

"make && make test" in a terminal window.

Many lines of output scroll by rapidly in the terminal window. In a minute or so, you’ll be returned to the command prompt.

Deploying the boxes Application

The application has been built, and we have an executable binary. We must now copy the binary to the /usr/bin/ directory. This allows the shell to find it when we try to use it.

For some applications, this might be all you have to do. In other cases, you might need to copy additional files, such as man pages and config files, into locations in the filesystem. The latter is what we have to do with our new application because it was in the build instructions.

File copy commands from GitHub.

Use sudo to run these commands. The first command copies a man page into the man1 directory:

sudo cp doc/boxes.1 /usr/share/man/man1

"sudo cp doc/boxes.1 /usr/share/man/man1" in a terminal window.

Next, copy the global config file to a directory in /usr/share/:

sudo cp boxes-config /usr/share/boxes

"sudo cp boxes-config /usr/share/boxes" in a terminal window.

Finally, copy the binary to /usr/bin:

sudo cp src/boxes /usr/bin

"sudo cp src/boxes /usr/bin" in a terminal window.

Testing the boxes Application

Let’s see if it all works! Try to open the man page for the boxes command.

man boxes

"man boxes" in a terminal window.

That’s encouraging! You see a man page telling you how to use the boxes command.

"boxes man" page in a terminal window.

Press “Q” to leave the man system and try to use the boxes command.

echo How-To Geek | boxes

"boxes How-To Geek" in a terminal window.

And we get the response:

boxes output in a terminal window.

This might seem slightly underwhelming considering all the effort you’ve gone to, but the point of this exercise was to walk you through pulling back a repository from GitHub and building the application.

The boxes command allows you to wrap text that’s piped to it in a wide variety of frames. Some of them could be used as comments in source code files. The format above would work as a comment in a C source code file, for example. Others are purely decorative. The -d (design) option allows you to choose the style of the frame.

echo How-To Geek | boxes -d whirly
echo How-To Geek | boxes -d c-cmt2

"echo How-To Geek | boxes -d whirly" in a terminal window.

There’s a long list of designs from which you can choose. To see them all, use this command:

boxes -l | less

Build Complete

The steps to build from source are usually straightforward:

  • Review the build instructions on the repository.
  • Check you have the required tools installed and install any that are missing.
  • Clone the repository to your computer.
  • Follow the build instructions, which are often as simple as typing make.
  • Copy the file(s) to the required locations.

If there are steps in the build instructions that are unclear, see if the project has a forum or community you can send a question to. If the application has a website, they might have a “Contact Us” page. The developer who maintains the boxes project has his email on the “About” page of the boxes website. That’s a generous gesture on his part, and typical of the wider open source community.

Dave McKay Dave McKay
Dave McKay first used computers when punched paper tape was in vogue, and he has been programming ever since. He is now a Data Protection Officer and has worked as a freelance programmer, manager of an international software development team, and an IT services project manager. Dave is a Linux evangelist and open source advocate.
Read Full Bio »