gettingOff.tex

\chapter{Getting off the ground}
\label{ch:gettingOff}

\index{command line}
\index{Linux}
\index{Unix}
Before we begin our study of object-oriented systems proper, we'll introduce
the command-line toolset we'll be using to construct our programs. We'll take
each of the most important tools out of our toolbox, lay them out before us on
a little mat, and learn what they're for.

\section{Why the command line?}

\index{CLI (command-line interface)}
\index{GUI (graphical user interface)}
Developing software in a command-line environment (sometimes abbreviated
``CLI'' for \textbf{command-line interface}, as opposed to a
``GUI\footnote{Commonly pronounced ``gooey.''}'' or \textbf{graphical user
interface}) involves typing white text in little black boxes. It requires
memorizing and regurgitating a variety of obscure commands. It demands exact
adherence to an inconsistent syntax, and exacts heavy penalties for mistakes,
all while providing only a very crude and clunky-looking interface.

It's natural to wonder why we would want to do this. After all, aren't
computer systems immeasurably more sophisticated now? If even end users run
fancy, graphical, forgiving apps, shouldn't computer scientists expect even
easier-to-use and sexier-looking stuff?

It may seem so, and in terms of the \textit{power} the tools provide, we'll
discover that indeed software developers are aptly equipped. But in some ways
it's a false expectation to assume that our toolset would be as \textit{easy}
to operate as that of an everyday user. After all, which is easier: to drive a
car, or to be a mechanic? Even though I enjoy cruise control and
auto-adjusting seats, I don't find it strange at all to learn that mechanics
still use socket wrenches to adjust piston assemblies.

Much of what makes a CLI so powerful is its expressiveness. A driver can press
any of the three or four cruise control functions the manufacturer provided.
But a mechanic can take any of hundreds of tools, tweak dozens of different
parts, and combine these adjustments in uncountable ways. That's the kind of 
flexibility the command line provides.

The difference between a CLI and a GUI is that with the latter, the user can
essentially do \textit{only what the tool designer anticipated she would want
to do.} There's no way she can express something that isn't one of the
tailor-made menu options.

When you use the command line, think of it as composing sentences, word by
word. A GUI comes with a repertoire of standard sentences you can choose from.
That makes it easy to do standard things, and hard to make silly mistakes. But
a CLI, being inherently language-based, is immeasurably more flexible. You can
write any (legal, grammatically correct) sentence you choose, even one the
designers of the CLI never thought of, and even one that you didn't know you'd
want to type until a moment ago. The bits and pieces can be combined in a
myriad of ways, just as nouns and verbs can.

\index{Finlayson, Ian}
There are other reasons as well that many developers live on the command line.
Among them are\footnote{Thanks to Ian Finlayson for capturing much of this
list.}:

\begin{itemize}
\itemsep.1em

\item \textbf{Speed.} It turns out to be way, way faster to type commands --
in combination with the various shortcuts and recall/edit operations -- than
it is to sift through menu options and such with a mouse. Trust me.

\index{remote access}
\index{shell}
\item \textbf{Remote access.} When you're running programs on your own device,
it's possible to do it with a GUI. But computer scientists very often have to
connect over the network to distant machines in order to tell them what to do.
Every time you need to configure a web server, for instance, or update a
publicly-accessible database, or run a time-consuming job on a parallel
cluster, or correct the data on your mobile device, you need a way to issue
commands to another machine through a very low-bandwidth channel. Opening a
command line ``shell'' to that remote device is by far the most common and
effective way to do this.

\index{scriptability}
\item \textbf{Scriptability.} There's just no good way to automate a sequence
of GUI operations. To explain to someone else how to accomplish something, you
have to painfully walk them through each operation (``go to the Start menu and
find Accessories, then in the Math menu choose Calculator...when it comes up,
right-click in the background and enable Advanced Options...'') which is
tedious and error-prone. It'd be nice if you could just send them a custom
command which would do all that. As a matter of fact, it would be nice if
\textit{you} could make a custom command which would do all that, so that you
could execute it many times without rehashing the same rigmarole. You'll find
that CLIs are eminently automatable in this way. You can create custom
commands called ``scripts'' that are combinations of other interacting
commands, and in this way you become master of your whole world.

\index{Cygwin}
\index{Mac OS X}
\index{Microsoft!Windows}
\index{Raspberry Pi}
\index{Kindle}
\index{Terminal application}
\item \textbf{Consistency.} Graphical user interfaces are more different from
each other than CLIs are. Partly this is because nearly any CLI you're likely
to use is Unix/Linux-based\footnote{For our purposes, you can consider the
terms ``Unix'' and ``Linux'' exact synonyms. The Mac OS X command line
(available through the ``Terminal'' app) is Unix-based, too. Windows machines
aren't, but programs like ``Cygwin'' can be downloaded for free and provide a
Linux-like command-line veneer over the operating system.}, and hence they all
``speak the same language.'' It's great to be able to log on to different
laptops, web servers, your phone, your Kindle, or a Raspberry Pi and get the
same prompt that understands the same stuff.

\index{Linux}
\index{Unix}
\index{CLI (command-line interface)}
\item \textbf{Stability.} CLIs rarely change. When they do, it's very very
rarely in a non-backwards-compatible way. By contrast, every time a new
graphical user interface is released, you have to go through a period of
hunting around and finding out where everything is. With Unix/Linux, you can
literally run commands that were written last century and they will likely
still work as is.

\end{itemize}

There's always a few students who, despite the above benefits, resist learning
this material at first. I get it. It's like learning a new language, and the
immense effort to understand an alien world sure doesn't feel like it's going
to pay off any time soon. All I can say is that if you're not convinced it's
worth it, for now just think of it as something you have to master ``just
because your professor and the industry says so.'' My hope is that by the end
of this course, you're pleasantly surprised by seeing some payoff for your
hard work.


\section{The filesystem}
\index{filesystem}
\index{file}
\index{tree}
\index{directory}
\index{folder}

Okay. The backdrop for all our use of the Linux command-line interface is the
\textbf{filesystem}.\footnote{Often, not always, written as a single word as I
have it here.} Any general-purpose computer, no matter its architecture or OS,
has an area of permanent storage for user data. Interestingly, and
conveniently, all computers organize their filesystems in pretty much the same
way: as a \textbf{tree} of \textbf{files} and \textbf{directories}.
(Windows/Mac users will be familiar with the term ``\textbf{folder},'' which
\textit{means exactly the same thing as ``directory.''}) In what follows, we'll
be using a different syntax (text instead of visual icons) to work with what is
conceptually the same organizational structure you're used to on your own
computer.

\subsection{Files and directories}

\index{filesystem extension}
A file is simply any named chunk of stuff on your disk. Images, .mp3 tunes,
Word docs, and (importantly) plain text files are all in this category. On
Windows, you're used to each of these files having a filesystem ``extension''
designating its type: ``\texttt{.docx}'' means a Word doc, and
``\texttt{.jpg}'' means an image file, for example. This is sort of true with
Linux, although the rules are a bit looser. Not all files have extensions at
all, and when they do, it's more a signal that they're intended to be treated a
certain way than it is a hard-and-fast requirement.

\index{java file@\texttt{.java} file}
\index{source file}
\index{Microsoft}

The most important files you'll work with in this class will have a
\texttt{.java} extension. These are your Java \textbf{source files}. You'll
also work with other various supporting files to make all the tools work
correctly. It's important to realize that \textit{a file is fundamentally just
some data, which can theoretically be opened and dealt with by any program}.
When we say that \texttt{HamletPaper.docx} ``\textit{is}'' a Word doc, what we
really mean is that its data is formatted in a certain way that the Microsoft
Word application expects to see, so it can render it on the screen for editing.
But it is possible to open that same \texttt{HamletPaper.docx} file with other
programs and manipulate its contents. This may seem sketchy, but it is actually
a force for good.

\index{text file}
In particular, you'll be tempted this semester to think of a \texttt{.java}
file as ``a \texttt{vim} file,'' in the same way that you may think of an
\texttt{.xls} file as ``an Excel file.'' I hope to break you of this habit, as
you learn to see a file as text or data that is actually independent of what
kind of program might be used to open and manipulate it.

\index{directory}
A directory is a container for files \textit{and also other directories}. That
last italicized phrase is what gives rise to the overall tree structure of the
filesystem, as discussed in the following section.

%\index{Foreman, George}
By the way, every file and directory \textit{in a particular directory} must
have a unique name. You can't have a file called ``\texttt{DireStraits.mp3}''
and another one also called ``\texttt{DireStraits.mp3}'' sitting there in the
same folder: it's a name collision. However, it's perfectly permissible to have
two files with the same name in different directories. This is kind of like how
there isn't more than one ``Stephen'' in my immediate family (that would be
confusing\footnote{With apologies to boxing legend George Foreman, who named
all four of his children ``George.'' That practice is not
filesystem-compatible.}), but there are of course many ``Stephens'' in the
world.

\subsection{The filesystem tree}

\index{tree}
\index{filesystem}
\index{directory!parent}
\index{parent directory}
The files and directories in a filesystem form a nested, hierarchical
structure called a \textbf{tree} (see Fig.~\ref{fig:tree}). I have drawn two
kinds of nodes in this tree: directories (yellow ovals) and files (blue
boxes). As expected, some of the directories have arrows coming out of them,
but none of the files do. The elements that a directory is pointing to are the
contents it contains: \textit{e.g.}, the left-most ``\texttt{america}''
directory contains another directory (``\texttt{nation}'') and also the file
\texttt{A.txt}. We use the term \textbf{parent directory} to mean the
directory immediately above an entry in the filesystem; the left-most
\texttt{A.txt} file's parent directory is the \texttt{america} directory we
just spoke of.

\begin{figure}[ht]
\centering
\includegraphics[width=0.9\textwidth]{tree.png}  %650x300
\caption{The Linux filesystem, in pictorial form.}
\label{fig:tree}
\end{figure}

In order to keep you on your toes, I've given several entries in this example
filesystem the same name: in addition to a couple different \texttt{america}s,
we've got several \texttt{states}, multiple different \texttt{A.txt}s, etc. In
no case, however, are the duplicately-named entries in the same directory.
(Convince yourself of that fact.)

\subsubsection{Only one surprise}

\index{Microsoft!Windows}
So far this is pretty easy. And it won't get much harder. But here's the one
thing you have to get used to: with a CLI, \textit{we won't ever actually see
that filesystem picture visually.} It's there, but we don't explicitly view it
in graphical form. Instead, there will be a textual way of referring to every
file and directory. It's straightforward, but can be a bit of a shock to those
coming from point-and-click systems like Windows.

\subsection{The ``current'' (or ``working'') directory}

\index{directory!current}
\index{directory!working}
\index{current directory}
\index{working directory}
One vital concept to grasp is that every time we issue a command or run a
program in Linux, we are doing so \textit{within the context of a particular
directory}. Conceptually, we think of being ``in'' a certain directory at any
point in time. We call this directory ``the \textbf{current directory}'' or
``the \textbf{working directory}'', and we'll learn commands to find out what
it is and to change it to something else.

Which one we're ``in'' has a crucial impact on what happens when we execute a
command. For instance, if our current directory is the far-left
\texttt{america} directory, and we issue a command that does something to
``\texttt{A.txt}'', it would act on the left-most \texttt{A.txt} file, since
it's the one within the current directory. But if our current directory were
\texttt{unitedstates}, ``\texttt{A.txt}'' would instead mean the far-right blue
node.

I've found that failure to understand the ``current directory'' concept is one
of the most common trouble spots for beginning Linux programmers.

\subsubsection{The root directory}

\index{directory!root}
\index{root directory}
\index{tree}

Okay, back to the filesystem as a whole. At the top of the tree is the
\textbf{root directory}, which has no parents. (This is often disorienting to
non-computer-scientists, since in the real world you may have noticed that
trees actually grow \textit{up}, not down. But in computer science, we always
draw trees growing down from the root.)

\index{backslash}
\index{forward slash}
\index{slash}
\index{Microsoft!Windows}
The root directory is the anchor point of the entire filesystem: it ultimately
contains everything under it. It also has a very strange name: ``\texttt{/}'',
pronounced ``slash.'' (This is a ``forward slash,'' by the way, to the left of
your right-most Shift key, not a ``backslash.'' Oddly, most Windows systems
use a backslash ``\texttt{\textbackslash}'' for this instead.) Stay awake,
because this ``\texttt{/}'' character will shortly mean something very
different as well.

\subsubsection{Paths}

\index{path}
\index{directory}
\index{file}
It should be apparent to you that as a consequence of this nested tree
structure, you can ``reach'' every element from the root directory by
traversing from arrow to arrow. Furthermore, you can do so in only one way.
For instance, the \texttt{B.java} file can be reached from the root by going
from ``\texttt{/}'' to \texttt{unitedstates} to \texttt{B.java}. And that's the
\textit{only} way to get there. You can reach \texttt{loveLetter.txt} by going
from ``\texttt{/}'' through \texttt{united}, \texttt{states}, and
\texttt{america}, in that order. This is true for every file and directory.

What this means is that every entry has a unique \textbf{path}, and we can
express it in text as well as in a diagram. Take the \texttt{B.java} file for
example. Its path is:

\quad\quad \texttt{/unitedstates/B.java}

\index{slash}
Look very carefully at that string as we dissect it. The most important thing
to grasp is that the two slash (``\texttt{/}'') characters \textit{each mean
something different}. The first one means ``the root directory, which is called
slash.'' But the second one is merely a separator, delimiting the
\texttt{unitedstates} from the \texttt{B.java}. So this path means
``start at the \textit{root} directory, go down to its \texttt{unitedstates}
entry (which itself is a directory), and there you have the \texttt{B.java}
file.''

Similarly, the path to \texttt{loveLetter.txt} is:

\quad\quad \texttt{/united/states/america/loveLetter.txt}

\index{slash}
(Note that the slash between \texttt{united} and \texttt{states} makes all the
difference in the world: if it weren't there, we'd be starting our descent
through the right-most \texttt{unitedstates} directory as before.)

\index{path!absolute}
\index{absolute path}
\index{planet}
\index{path!relative}
\index{relative path}
These paths are called \textbf{absolute paths} because they \textit{start with
a slash}. This means that they give the complete, start-from-the-top position
of a particular file or directory. It's kind of like referring to a building
by its complete address, including city, state, zip code, country, and planet.
Often we want a short-hand way of referring to an entry without specifying its
entire absolute path. To do so, we use a \textbf{relative path}.

\index{directory!current}
\index{current directory}
A relative path is relative \textit{to the current directory}. And it does
\textit{\textbf{not}} begin with a slash. Instead, it gives directory names,
separated by slashes, indicating where to start descending from the
\textit{current} directory.

For example, let's say the current directory was ``\texttt{/states}''. And
suppose I used this relative path:

\quad\quad \texttt{united/states/mysteryNovel.txt}

(Note carefully that it has \textit{no} initial slash!) This relative path
would start at the \textit{current} directory (\texttt{/states}) and from there
traverse down to \texttt{united}, \texttt{states}, and then finally
\texttt{mysteryNovel.txt}. Obviously, where you end up is critically dependent
on where you start -- on what the current directory is.

\index{directory!current}
\index{current directory}
To test your understanding, realize that in this case where the current
directory is \texttt{/states}, there is no such file called
\path{united/states/america/loveLetter.txt}. In fact, even 
\path{united/states/america} doesn't exist. However, if we changed the
current directory to be the root (``\texttt{/}''), suddenly the relative path
\path{united/states/ america/loveLetter.txt} would be legit.

\section{Linux A-B-C's}

\index{Unix}
\index{Linux}
\index{filesystem}
\index{file}
\index{directory}
With the filesystem always hovering in the background, let's introduce the
first basic Linux commands to work with the files and directories. These
commands are so basic that they're like the alphabet of speaking any Linux
sentence. Using them should eventually be as familiar and effortless to you as
clicking the mouse.

\index{prompt}
\index{dollar sign (\texttt{\$})}
In all that follows, I will precede anything you are to type on the Linux
command line with a dollar sign \textbf{prompt}:

\begin{Verbatim}[fontsize=\small]
$
\end{Verbatim}

To execute a command, you do \textit{not} type the prompt itself: it's just
there to indicate ``now is an appropriate time and place to enter a Linux
command.'' Just type the stuff after it.

\index{directory!current}
\index{current directory}
Also, depending on your system and configuration, your prompt may look
different or have other information in it. One common setting, for instance,
is for the current directory to always appear as the prompt. (I personally
hate that, since it makes different commands start at different horizontal
locations as I work, plus it consumes a lot of space.) No matter what, though,
just mentally substitute ``the dollar sign'' for ``whatever your Linux prompt
is.''

\newcommand{\bigline}{\vspace{-.3in} \begin{center} \line(1,0){300} \end{center}}


\begin{enumerate}
\itemsep.1em
\item \textbf{\texttt{pwd}}

\index{pwd@\texttt{pwd}}
Your first command stands for ``\textbf{p}rint \textbf{w}orking
\textbf{d}irectory,'' and simply tells you what the current directory is at any
point in time. For example:

\begin{Verbatim}[fontsize=\small]
$ pwd
/united/states
\end{Verbatim}

tells you that you're currently ``in'' the \texttt{states} directory, which is
contained within the \texttt{united} directory, which is contained within the
root directory.

\textbf{Tip:} get in the habit of typing \texttt{pwd} a \textit{lot},
especially at first. Get ingrained in your brain the question ``where am I in
the filesystem right now?'' because it matters, yet is not in your face except
when you type this command.

\bigline
\item \textbf{\texttt{cd}}

\index{cd@\texttt{cd}}
\texttt{cd} stands for ``\textbf{c}hange \textbf{d}irectory'' and is how you
move to another place. You give it an \textbf{argument} (kind of like passing
a parameter to a function call in a programming language, although we don't
use parentheses or commas here) which is where you want to go:

\begin{Verbatim}[fontsize=\small]
$ cd  /america/nation
\end{Verbatim}

Here, I've specified an absolute path. If I now execute \texttt{pwd}, I see
that it worked:
\begin{Verbatim}[fontsize=\small]
$ pwd
/america/nation
\end{Verbatim}

\index{relative path}
\index{path!relative}
\index{absolute path}
\index{path!absolute}
More common is to specify a relative path. If we first go back to our original
location:

\begin{Verbatim}[fontsize=\small]
$ cd  /united/states
$ pwd
/united/states
\end{Verbatim}

we can then say ``go \textit{from here} into the \texttt{america} directory'':

\begin{Verbatim}[fontsize=\small]
$ cd  america
$ pwd
/united/states/america
\end{Verbatim}

\index{cd@\texttt{cd}}
\index{pwd@\texttt{pwd}}
I can't overestimate how important it is to notice that in the previous
\texttt{cd} command, I did \textit{not} include a slash before
\texttt{america}. If I had, it would have been an absolute path, and I would
have gone to a completely different part of the filesystem:

\begin{Verbatim}[fontsize=\small]
$ cd  /america
$ pwd
/america
\end{Verbatim}

\subsubsection{``Special'' directory shortcuts}

\index{directory!shortcuts}
\index{special directory shortcuts}
This is a good time to mention that when you are specifying paths, there are
three very common shortcuts that you'll want to know about.


\begin{itemize}
\itemsep1em

\index{directory!current}
\index{current directory}
\item The current directory: \texttt{\textbf{.}}

A plain-ol' dot (period) is used to mean ``the current directory.'' There's no
obvious uses for this yet, but believe me, it comes up \textit{all} the time,
so just memorize it. A useless example for now:

\begin{Verbatim}[fontsize=\small]
$ pwd
/united/states
$ cd  ./america
$ pwd
/united/states/america
\end{Verbatim}

So ``\texttt{./america}'' is another way of saying ``\texttt{america}''. (Told
you this example was useless.)

\item The parent directory: \texttt{\textbf{..}}

\index{directory!parent}
\index{parent directory}
More immediately useful is the double-dot, which means ``the parent of the
current directory.'' If we're currently in \path{/united/states} and want to go
to \texttt{/united}, one way to do it is:

\begin{Verbatim}[fontsize=\small]
$ cd  ..
$ pwd
/united
\end{Verbatim}

We can also join this with additional relative path stuff to move around the
hierarchy in various ways:

\begin{Verbatim}[fontsize=\small]
$ pwd
/states/united
$ cd  ../usa
$ pwd
/states/usa
\end{Verbatim}

\index{directory!sibling}
\index{sibling directory}
\index{directory!child}
\index{child directory}
Here we went to a ``sibling'' directory by ``going up one, and then down to a
different child.''

\item The home directory: \texttt{\textbf{\freakingtilde}}

\index{directory!home}
\index{home directory}
A shortcut for ``the home directory'' (which means ``the current directory when
you first log in'') is a tilde. It's commonly used in conjunction with other
relative path stuff, like the last double-dot example, above.

Your home directory will probably be something like \texttt{/home/joeschmo}
(which you can verify by just typing \texttt{pwd} when you first log in).
Suppose it is. Then, you can use the tilde:

\begin{Verbatim}[fontsize=\small]
$ pwd
/somewhere/else/in/the/filesystem
$ cd  ~/shortStories/scifi
$ pwd
/home/joeschmo/shortStories/scifi
\end{Verbatim}

to go to any of your subdirectories.

\end{itemize}

\bigline
\item \textbf{\texttt{ls}}

\index{ls@\texttt{ls}}
While \texttt{pwd} tells you what the current directory is, the \texttt{ls}
command (which sort of stands for ``\textbf{l}i\textbf{s}t'') gives you its
contents. If I type it while in the \texttt{/america} directory, for instance,
it tells me:

\begin{Verbatim}[fontsize=\small]
$ ls
nation   A.txt
\end{Verbatim}

These are the two entries from Figure~\ref{fig:tree}.

\index{ls@\texttt{ls}}
A few gotchas to be aware of. First, there's no way from that listing to
tell that \texttt{nation} is a directory whereas \texttt{A.txt} is a file. If
you want to see that, you need to add the ``\texttt{-l}'' option (a minus sign
followed by the lower-case letter ``ell''):

\begin{Verbatim}[fontsize=\footnotesize]
$ ls  -l
-rw-r--r-- 1 kyloren   sithlords   17 Sep  5 16:21 A.txt
drwxr-xr-x 2 kyloren   sithlords 4096 Sep  5 16:21 nation
\end{Verbatim}

Lots of clutter here. The key points:

\begin{compactitem}[-]
\item The far-left character on each line is either a ``\texttt{-}'' or a
``\texttt{d}'', indicating file or directory.
\index{file!owner}
\item Files in Linux have ``owners,'' meaning specific users who created them
and have permissions to manage them. Both of these entries are evidently owned
by user \texttt{kyloren}.
\item The \texttt{17} and \texttt{4096} are file sizes (in bytes).
\item You can see the date and time each entry was last modified.
\end{compactitem}

\index{long file listing}
\index{option}
The ``\texttt{-l}'' stands for ``\textbf{l}ong file listing.'' Most Linux
commands have a bevy of different options you can specify when you execute
them, most often beginning with a minus sign.

Another important one for the \texttt{ls} command is ``\texttt{-a}'' which
stands for ``\textbf{a}ll files, please.'' If that sounds like a strange
option, that's because it is. It turns out that \texttt{ls} by default doesn't
show you all the files; in particular, \textit{it omits those whose names start
with a dot (.).} Why? There are reasons. The only time this will be relevant to
you soon is if you want to work with your \texttt{.bashrc} file.\footnote{If,
in your \textit{home} directory, you create a file with \texttt{vim} called
literally \texttt{.bashrc} (pronounced ``dot-bash-arr-see'') then whatever
Linux commands it contains will be executed automatically every time you log
in. Once you get proficient with Linux, it's very handy to put shortcuts,
aliases, and various preferences in it.} You'd have to type ``\texttt{ls -a}''
in your home directory to actually see it in the listing.


\bigline
\index{cd@\texttt{cd}}
\index{pwd@\texttt{pwd}}
\index{ls@\texttt{ls}}
\vspace{-.1in}
\begin{tabular}{m{.5in}m{3in}}
{\Huge \leftthumbsup} & The above three commands -- \texttt{pwd}, \texttt{cd},
and \texttt{ls} -- go together like Luke, Han, and Leia. Get in the habit of using them literally every minute you're working on the Linux command line.
\end{tabular}
\vspace{.1in}
\bigline

\item \textbf{\texttt{mkdir}}

\index{mkdir@\texttt{mkdir}}
To create a directory in the first place, use the \texttt{mkdir} command and
give it the name:

\begin{Verbatim}[fontsize=\small]
$ mkdir  evilplans
\end{Verbatim}

This new \texttt{evilplans} directory will be created inside the current
directory.

Note carefully that \textit{making a directory does not automatically put you
in it!} Lots of beginners mistakenly think this will happen, but you can see
that it does not:

\begin{Verbatim}[fontsize=\small]
$ pwd
/home/kyloren
$ mkdir  evilplans
$ pwd
/home/kyloren
\end{Verbatim}

\index{cd@\texttt{cd}}
You have to \texttt{cd} as a separate step if you want to now be \textit{in}
\texttt{evilplans}:

\begin{Verbatim}[fontsize=\small]
$ cd  evilplans
$ pwd
/home/kyloren/evilplans
\end{Verbatim}

\index{directory!parent}
A useful option to \texttt{mkdir} is the ``\texttt{-p}'' option which means
``make all \textbf{p}arent directories as necessary.'' This lets us create a
deeply-nested structure all in one fell swoop:

\begin{Verbatim}[fontsize=\small]
$ mkdir  -p  find/luke/skywalker/now
$ cd  find/luke/skywalker/now
$ pwd
/home/kyloren/find/luke/skywalker/now
\end{Verbatim}

\bigline

\item \textbf{\texttt{cp}}
\index{cp@\texttt{cp}}
\index{file!copying}

To make a copy of a file, use \texttt{cp} and give it \textit{two} arguments,
a source and a destination. If I type:

\begin{Verbatim}[fontsize=\small]
$ cp  A.txt  Q.txt
\end{Verbatim}

I will now have two exact copies of the file which can be independently
modified:

\begin{Verbatim}[fontsize=\small]
$ ls
nation   A.txt   Q.txt
\end{Verbatim}

I can also use this to make a (same-named) copy of a file to a different
location, by providing a directory as the second argument:

\begin{Verbatim}[fontsize=\small]
$ cp  A.txt  /states/usa
$ cd  /states/usa
$ ls
A.txt
\end{Verbatim}

\bigline

\item \textbf{\texttt{mv}}
\index{mv@\texttt{mv}}
\index{file!renaming}

\texttt{mv} has pretty much the same effect as \texttt{cp}, except that it
does not retain the original copy. This command can be used to rename a file
(``\texttt{\$ mv oldfilename newfilename}'') as well as to change a file's
location.

\bigline

\item \textbf{\texttt{vim}} (and \texttt{vimtutor})
\index{vim@\texttt{vim}}

It's really ludicrous to include this command in amongst all the others, when
its ins-and-outs could (and do) occupy entire textbooks in their own right.
\texttt{vim} is a text editor program with a zillion amazing features which
you will use this semester to write your programs. The normal way of creating
a file, in fact, will be this:

\begin{Verbatim}[fontsize=\small]
$ vim  notesOnTheResistance.txt
\end{Verbatim}

or this:

\begin{Verbatim}[fontsize=\small]
$ vim  DestroyGalacticRepublic.java
\end{Verbatim}

after which you will do loooooooooooots of other stuff way beyond the scope of
this book. That stuff will be cryptic and agonizing at first, but will
eventually become second-nature and give you the tremendous text editing power
you need to be a truly efficient software developer. It's kind of like
learning to use the Force for the first time.

\index{vimtutor@\texttt{vimtutor}}
For now, I'll make this (strong) suggestion: to learn \texttt{vim} for the
first time, type this command (all one word) at the command line:

\begin{Verbatim}[fontsize=\small]
$ vimtutor
\end{Verbatim}

\index{Coke}
Grab a Coke, and spend 30-40 minutes patiently reading and following the
instructions. This tutorial is quite good, and will teach you the very basics
of getting a file created and edited with this incredible tool.

\bigline

\item \textbf{\texttt{git}}
\label{introduceGit}
\index{git@\texttt{git}}
\index{version control system}

\texttt{git} is another one that doesn't really fit in this list, since it's
much more than just ``a command.'' For now, though, all you need to understand
is that it's a \textbf{version control system} that allows you to track and
manage the changes you make to your software over time.

Up until now, you've been dealing with a paradigm like ``the IDE always has the
most recent copy of my code, and that's the only version of it that exists.''
You'll need much more flexibility than that when you work on large systems.

Here's all you need to know at present, though:

\begin{compactitem}
\index{git@\texttt{git}!\texttt{git init}}
\index{repository@``repo'' (repository)}
\item The command ``\texttt{git init .}'' (don't forget the dot at the end,
after a space) creates a git \textbf{repository}
(or ``\textbf{repo}'') in the current directory. That just means that your
current directory, and everything under it, are now ``under git's
management.''
\index{git@\texttt{git}!\texttt{git add}}
\item You use ``\texttt{git add}'' to make git aware of
one or more files that you want it to track from that point forward. You'll
type ``\texttt{git add }file1 file2 file3'' or however many files you want
to add at that point. Ordinarily you'll want to \texttt{git add} all of your
\texttt{.java} files.
\index{git@\texttt{git}!\texttt{git commit}}
\index{commit}
\index{snapshot}
\item When you've made a
significant change to one or more of your files that you want git to be aware
of, you'll enter this command:
\begin{Verbatim}[fontsize=\footnotesize]
$ git  commit  -a  -m  "A message describing the change."
\end{Verbatim}
Each such change is called a \textbf{commit}. Think of it as taking a
snapshot of your code that you can return to later.
\index{git@\texttt{git}!\texttt{git status}}
\index{git@\texttt{git}!\texttt{git log}}
\item ``\texttt{git status}'' and ``\texttt{git log}'' are two useful
commands that show the current state of your files as git sees them, and a
history of all the different commits you've made. Type them occasionally just
to get a feel for what kind of information they show.
\end{compactitem}

We'll talk much more about \texttt{git} later. For now, just know that it
exists, and type the above commands verbatim when prompted.

\bigline
\item \textbf{\texttt{javac}} and \textbf{\texttt{java}}

\index{javac@\texttt{javac} (compiler)}
\index{java@\texttt{java} (virtual machine)}
\index{compiler}
\index{virtual machine}
\index{JVM (Java Virtual Machine)}
\index{JDK (Java Development Kit)}
\index{J2SE (``Java 2 Standard Edition'')}
\index{JRE (Java Runtime Environment)}

\index{source file}
Now, finally to some programming stuff. On your Linux system, the Java
\textbf{compiler} (\textit{i.e.}, the program that converts your source code
into the form the computer needs to run it) is called \texttt{javac}, and the
\textbf{virtual machine} (the interpreter that runs your compiled code) is
called \texttt{java}. Both of these are part of the \textbf{JDK}, or ``Java
Development Kit,'' that you install in order to program in Java.\footnote{Just
to confuse you, the JDK has sometimes been called the ``Java SDK'' (``Java
Software Development Kit'') and the ``J2SE'' (``Java 2 Standard Edition'') in
the past, and you'll likely run across those acronyms as well. To confuse you
even more, the software you need to simply \textit{run} a Java program (as
opposed to writing your own) is called the ``JRE'' -- Java Runtime
Environment. Finally, to confuse you yet further, Java version numbers were
originally all ``one-dot-something'' (like ``Java 1.3'') but in 2004 they
ditched the ``one-dot'' and started naming the versions after the second
number alone. (So, the successor to ``Java 1.4'' was ``Java 5.'') This book
assumes you're on Java 17 or later, by the way.}


\index{compiler}
To compile, you give \texttt{javac} all the Java files that are part of your
program:

\begin{Verbatim}[fontsize=\scriptsize]
$ javac  DestroyGalacticRepublic.java  Bombs.java  SinisterPlans.java
\end{Verbatim}

\index{java file@\texttt{.java} file}
\index{class file@\texttt{.class} file}
\index{main method@\texttt{main()} method}
which will either produce a \texttt{.class} file for each \texttt{.java} file,
or compiler errors for you to read. Finally, to run it, you give \texttt{java}
the name of \textit{the class that contains your \texttt{main()} method}:

\begin{Verbatim}[fontsize=\footnotesize]
$ java  DestroyGalacticRepublic
\end{Verbatim}

(Notice we don't include ``\texttt{.java}'' or ``\texttt{.class}'' here, and
notice we don't mention every Java class, only the one that has the
\texttt{main()}.)

\end{enumerate}

\pagebreak
\section{The quickest path through the woods}

Whew. That was a lot. It's kind of like moving to another country: every
little thing, all at once, seems different.

All I can do is promise you it will get easier as you get used to that new
country. And there will be parts of it you will like -- maybe you'll even like
it better than the point-and-click country you grew up in.

\index{Hello World@``Hello, World"!'' program}
In the meantime, let's pull together all the steps to get a ``Hello World''
Java program running on the Linux command line.

\begin{enumerate}
\itemsep.1em
\item Log on to your Linux system (for instance, the UMW server or your Google
Cloud instance), however you do that.
\item Create a directory to hold your project:
\begin{Verbatim}[fontsize=\small]
$ mkdir  myFirstProgram
\end{Verbatim}

\item And make sure to actually go there:
\begin{Verbatim}[fontsize=\small]
$ cd  myFirstProgram
\end{Verbatim}

\item Create a git repo to manage this project:
\begin{Verbatim}[fontsize=\small]
$ git  init  .
\end{Verbatim}

(and of course don't forget that pesky dot at the end.)

\item Now create a Java file:
\begin{Verbatim}[fontsize=\small]
$ vim  HelloWorld.java
\end{Verbatim}

\textbf{(You are now in \texttt{vim}. Everything you learned during your
\texttt{vimtutor} session, and everything you can get from a zillion different
``vim cheat sheets'' on the Internet, is relevant now. Good luck.)}

\item Give it these contents:
\begin{samepage}
\begin{Verbatim}[fontsize=\small,frame=single]
class HelloWorld {
    public static void main(String args[]) {
        System.out.println("yo sup dawg");
    }
}
\end{Verbatim}
\end{samepage}

\item Save your file and exit \texttt{vim}.

\item Now compile it:
\begin{Verbatim}[fontsize=\small]
$ javac  HelloWorld.java
\end{Verbatim}

\item And, since it gave you no errors, run it:
\begin{Verbatim}[fontsize=\small]
$ java  HelloWorld
\end{Verbatim}

\item Finally, add the file to your repo:
\begin{Verbatim}[fontsize=\small]
$ git  add  HelloWorld.java
\end{Verbatim}

\item and commit it:
\begin{Verbatim}[fontsize=\small]
$ git  commit  -a  -m  "Finished chapter 1!"
\end{Verbatim}

\end{enumerate}

It's a big bright world ahead of us. Go take a break and I'll see you next
chapter.