.\" To see this man-page formatted, run it through
.\" mandoc -Tlint -Tascii | less -r
.\"
.\" Change Month, Day, Year to time of editing.
.Dd October 12, 2008
.Dt SMGL-SETUP 7
.Os "Source Mage GNU/Linux"
.Sh NAME
.Nm smgl-setup
.Nd introduction to configuring Source Mage GNU/Linux
.Sh DESCRIPTION
Welcome to Source Mage GNU/Linux!
.Pp
This manual describes the steps that you can and should take for a newly
installed Source Mage GNU/Linux system.
After finishing the minimal installation from the ISO itself, there is still
a lot of work to be done on the part of the user to bring the system to a more
usable and polished state.
This includes configuring the system, setting up networking, and so on.
Each section below will describe different things you can do with your new
system.
.Sh SYSTEM CONFIGURATION
The Source Mage installation provides some default settings for a baseline
system, such as
.Ev EDITOR Ns = Ns Pa nano .
Now would be a good time to configure some of those settings to suit your own
tastes.
Note that you can do this before or after updating your system, though it is
recommended that you configure some of these, such as your text editor and
timezone, before doing anything else.
.Ss Default Text Editor
You can change the default text editor either globally, by editing the
.Pa /etc/profile.d/editor.sh
script, or per user, by setting the
.Ev EDITOR
environment variable in your
.Pa .bashrc
or equivalent.
The default text editor set by the installer is
.Cm nano .
Make sure that you have your preferred text editor installed, else you will
get errors for trying to use an editor that doesn't exist on your system.
.Ss System Logger
You may optionally want to install a system logger.
You can have more than one logger installed at a time, but you can only have
one of them running (enabled) at a time or they will conflict with each other.
Some spells (optionally) depend on having a system logger, so it is
recommended that you install one.
You can view the possible system logging providers by running:
.Bd -literal -offset indent
gaze provides SYSTEM-LOGGER
.Ed
.Ss Pa /etc/sysconfig/
This directory is full of configuration files that provide different settings
for your entire system.
Some files you might want to edit would be:
.Bl -tag -width Pa/init
.It Pa facilities
Setup which programs should provide different services such as system logging
and the default display manager.
.It Pa hwclock
Set whether the hardware clock stores time in UTC format.
.It Pa keymap
Set the keymap to use in the console, as well as the font and whether UTF-8
should be enabled or not.
.It Pa locale
Define various locale information.
.It Pa init
Configure the init process, such as the default run level.
.It Pa shutdown
Configure whether to power off or just halt when shutting down.
.El
.Ss Timezone
You can set up your system's timezone by following these steps.
Look for your timezone in
.Pa /usr/share/zoneinfo .
Copy or link that timezone to the
.Pa /etc/localtime
file by running this command as root, using
.Pa Asia/Manila
as an example:
.Bd -literal -offset indent
cp (or ln -sf) /usr/share/zoneinfo/Asia/Manila /etc/localtime
.Ed
.Pp
Verify that everything is working correctly with the
.Xr date 1
command.
.Ss Networking
Source Mage has recently switched to a simpler system for managing network
connections using the Debian-based ifupdown interfaces system.
This basically involves editing the
.Pa /etc/network/interfaces
file to configure what the
.Xr ifup 8
and
.Xr ifdown 8
commands would do.
The
.Xr interfaces 5
manual page explains how to write the file.
Example configurations are also provided in the
.Pa /usr/share/doc/ifupdown/examples/
directory, specifically the
.Pa network-interfaces
file.
.Sh SYSTEM UPDATE
Once you are able to connect to the Internet, you can start upgrading your
system to the latest stable versions of the grimoires and sorcery, or switch to
other branches.
This is done through the
.Xr scribe 8
and
.Xr sorcery 8
commands as described below.
.Ss Updating Grimoires
A
.Cm grimoire
is Source Mage's repository of spells and is managed using the
.Xr scribe 8
command.
By default, only the
.Cm stable
grimoire is installed, but the version might be a bit dated by the time you
have installed Source Mage.
The command
.Bd -literal -offset indent
scribe update
.Ed
.Pp
will update all grimoires installed on your system.
You can add other grimoires, like the test grimoire, by running:
.Bd -literal -offset indent
scribe add test
.Ed
.Pp
More information about managing grimoires can be found in the
.Xr scribe 8
manual page.
.Ss Updating Sorcery
.Xr sorcery 8
is Source Mage's package management suite.
Make sure that it is up-to-date by running:
.Bd -literal -offset indent
sorcery update
.Ed
.Pp
You can choose which branch of sorcery to use through the
.Cm sorcery
menu.
Run
.Bd -literal -offset indent
sorcery
.Ed
.Pp
and go to the
.Ic Option
menu, then select
.Dq Sorcery Branch .
Be sure to update sorcery every time you switch branches.
In case something causes the update to fail and your sorcery scripts are
lost, run the following command to restore them:
.Bd -literal -offset indent
bash /root/sorcery.restore
.Ed
.Ss Configuring Sorcery Options
.Xr sorcery 8
lets you fine-tune compilation options to your hardware and your personal
preferences.
This is easily done through the
.Xr sorcery 8
menu.
Run the command
.Bd -literal -offset indent
sorcery
.Ed
.Pp
and go to the
.Cm Options
menu.
Here you are presented with a lot of options to customize how sorcery functions
or how spells are cast.
There are a few worth mentioning:
.Ss Optimize Architecture
Here you will be able to choose a microprocessor category, some pre-defined
optimization options, as well as additional options that you would want to be
passed to the compiler.
.Ss Feature Menu
This lists some Sorcery features which you can toggle on or off.
For example, you can choose whether Sorcery will create archives of installed
software, or whether to use ccache for accelerated upgrade compilations.
Note that
.Cm ccache
must be installed for this to work.
.Ss Prompt Delay
While casting spells, Sorcery will ask you questions regarding features or
actions to be taken.
It will wait for a given amount of time for you to answer before continuing
the cast, using the default answer (varies from spell to spell) if you don't
respond before it times out.
This feature allows you to set how long, in seconds, Sorcery has to wait before
proceeding; choose 0 to have sorcery just use the default values immediately,
although you won't be able to change any settings while casting spells if you
do this.
.Ss Tip
The status message at the bottom of the screen gives a brief explanation about
each option.
Feel free to play with various options, but be aware that if you don't know
what you are doing with some of the options, you could end up with drastically
different results than you might expect.
You can leave most settings, besides the compile options, at the default and
things should run just fine.
.Ss Rebuilding the system
After you have updated your grimoires and sorcery, you may choose to rebuild
all the spells installed on your system.
This step is optional, but recommended.
If you choose not to rebuild your system, then the options you selected for
sorcery will not take effect until the next time the spell is compiled, either
by forcing a recompile of the spell with:
.Bd -literal -offset indent
cast -c [spell]
.Ed
.Pp
or by upgrading to a new version of the spell.
You can rebuild every spell in the system by issuing the following command:
.Bd -literal -offset indent
sorcery rebuild
.Ed
.Pp
Optionally, you can first rebuild the toolchain before rebuilding the whole
system.
This will ensure that the toolchain will be using whatever optimizations you
set in
.Xr sorcery 8
when it recompiles the rest of the system.
You can rebuild the toolchain by running:
.Bd -literal -offset indent
cast -c binutils gcc g++ gettext glibc
.Ed
.Pp
After it's done, you can rebuild the system as indicated above.
You can skip g++ if you don't have it installed.
.Sh BEYOND A BASE INSTALL
You should now have fully working and updated base system, ready to be expanded
to your personal needs, whether for a desktop, a server, or anything else.
Where you go from here is really up to you.
Add more grimoires with
.Xr scribe 8 ,
search and view spells using
.Xr gaze 1 ,
or install or remove spells using
.Xr cast 8
and
.Xr dispel 8 .
Here are a few suggestions you might be interested in.
.Ss Command line chatting and surfing
Whether you are a command line type of person, or merely waiting for a proper
graphical interface to finish casting, you can still enjoy the use of your newly
set up Internet connection to go online.
You can chat on IRC with
.Cm irssi
and browse the web with one of many text browsers, such as
.Cm w3m ,
.Cm elinks ,
or
.Cm lynx .
For example,
.Bd -literal -offset indent
cast irssi elinks
.Ed
.Pp
will install both
.Cm irssi
and
.Cm elinks .
.Ss X Window System
Most window managers and desktop environments rely on the X Window System for
graphical capabilities.
If you are using the stable grimoire, you can install (monolithic) Xorg by
running
.Bd -literal -offset indent
cast xorg
.Ed
.Pp
On the other hand, if you are using the test grimoire, you can get the newer
(modular) Xorg with
.Bd -literal -offset indent
cast xorg-server
.Ed
.Pp
Note that you do not have to manually cast X if you are casting a spell that
depends on X, such as a window manager or desktop environment, since it will
automatically be pulled in as a dependency of the spell you are casting that
depends on it.
.Ss DE's and WM's
If you fancy setting up a full graphical environment, Source Mage provides
spells for most of the major desktop environments and window managers.
You can install GNOME 1 or 2, KDE 3 or 4, Xfce 4, or a whole host of other
window managers such as
.Cm awesome
and
.Cm fluxbox .
Most of these are in the
.Cm windowmanagers
section of the grimoires.
To list the spells available in that section, run
.Bd -literal -offset indent
gaze section windowmanagers
.Ed
.Pp
The desktop environment spells provide a special
.Ic profile
spell to make it easier to install the whole desktop using just one command.
These profile spells are as follows:
.Bl -tag -width Pa/kde4-profile
.It Pa gnome-profile
For GNOME 1.
.It Pa gnome2-profile
For GNOME 2.
.It Pa kde-profile
For KDE 3.
.It Pa kde4-profile
For KDE 4.
.It Pa xfce4-profile
For Xfce 4.
.El
.Pp
To install one of the desktops, for example Xfce 4, run the command
.Bd -literal -offset indent
cast xfce4-profile
.Ed
.Pp
.Em Note about KDE 4:
In order for a user to be able to use KDE 4, that user must belong to the
.Pa kde4
group.
Add a user to the kde4 group with this command:
.Bd -literal -offset indent
gpasswd -a [username] kde4
.Ed
.\" The following commands should be uncommented and
.\" used where appropriate.
.\" This next command is for sections 1, 6, 7 and 8 only.
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.\" .Sh EXAMPLES
.Sh SEE ALSO
.Xr scribe 8 ,
.Xr sorcery 8 ,
.Xr gaze 1 ,
.Xr cast 8 ,
.Xr dispel 8
.Pp
Visit the Source Mage GNU/Linux website:
.Lk http://www.sourcemage.org
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
The Tome and Cauldron Teams of Source Mage GNU/Linux
.\" .Sh BUGS
.