A Quick Start on DragonFly

August 30, 2004

This document covers a number of first steps to take with a newly installed DragonFly system. It assumes some experience with a command line, and moves quickly. Much of this information is covered in further depth in the Handbook; the minimum is presented here for the benefit of readers who are already familiar with the material, or just impatient.

1 Keeping up to date

cvsup, which is included in the base system, is used to copy fresh source code and up-to-date ports to your system. cvsup uses a configuration file to determine what to download. A number of example files are stored in /usr/share/examples/cvsup/ and will be used here.

1.1 Pulling in userland and kernel sources

In order to keep the operating system up to date, you need to pull down the source code you want to compile and install. This includes the userland and kernel source code. On the default of install of DragonFly, these sources are not installed. The source code for the userland and kernel are typically stored in /usr/src/.

To keep up-to-date source in /usr/src/:

# cvsup -h DRAGONFLY-MIRROR /usr/share/examples/cvsup/DragonFly-src-supfile
The -h option in the example above determines what server is used. For DRAGONFLY-MIRROR, substitute a cvsup mirror listed on the Download page on the DragonFly website.

'DragonFly-src-supfile' is a configuration file for cvsup that will get the latest version of the source code and put it in /usr/src. There are more example configuration files in /usr/share/examples/cvsup/ and you can also create your own. The latest version is only recommended for development; production systems should run the most recent release of DragonFly. For production systems, choose a particular release tag, such as 'DragonFly-release1_6-supfile' tag.

1.2 Updating the operating system

If your system is relatively quiescent, you can do this:

# cd /usr/src && make buildworld && make buildkernel
# make installkernel && make installworld && make upgrade
# reboot

If a build step fails, wait a short while and update using cvsup. DragonFly is under heavy development, and while it has remained remarkably stable, it is possible someone was in the middle of a commit while the source on disk was downloaded. If it does not work on a second try, report it to bugs.

When sending a question to bugs, please describe what you were doing at the time the error happened, and include the error data.

If your problem gets solved, please post a followup message to bugs explaining what the fix was; this will help others in the future who encounter the same problem, or people looking to fix unresolved problem reports.

If you have other programs running or users on your computer, it may be a good idea to reboot to single-user mode before running the installkernel or installworld targets, as the installation process removes and reads system software.

If you have a custom kernel config file in /usr/src/sys/i386/conf, replace make buildkernel and make installkernel with make buildkernel KERNCONF=KERNELNAME and make installkernel KERNCONF=KERNELNAME, where KERNELNAME is the name of that configuration file.

Once a full buildworld/kernel has been done, 'quickkernel' and 'quickworld' can be used instead for quicker results. Drop back to buildworld/installworld if the 'quick' targets cause errors.

2 Installing software

As of 1.4, DragonFly uses the NetBSD Packages Collection (pkgsrc) for third-party software.

To install pkgsrc (You must be root to do this):

# cd /usr
    # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
To build and install a package from source:
# cd /usr/pkgsrc/misc/screen
    # bmake install clean
To install a binary package (substitute URL of binary package here):
# pkg_add URL
For a quick guide, please see the documentation on the DragonFly website.

3 Getting to a Desktop

The two major requirements to get a "desktop" computer is installing Xorg, and installing a window environment.

3.1 Xorg

Xorg in pkgsrc is transitioning to a new version as of this writing; details will be placed here as soon as it is possible to provide a direct pointer to a single installation method.

It is possible, as root, to have Xorg probe your hardware, after installation, and build a suitable configuration file for your machine.

# Xorg -configure > xorg.conf.new

It's also possible to use the programs xorgcfg or xorgconfig to generate a configuration file. xorgcfg is graphical, and autoconfigures itself for display. If it has trouble displaying, try it with the '-textmode' argument. As a final option, xorgonfig is a text program that will attempt to display choices for building a working configuration. Both require some knowledge of the hardware located inside the computer. It may be useful to know the video card chipset and the hsync and vsync of the monitor being used.

Once the xorg.conf.new file is created, try starting xorg with that as the config file.

# Xorg -config xorg.conf.new

Assuming all goes well, this will place you in a minimal environment, using the program twm for layout. You'll see several xterms on the screen, from which Ctrl-Alt-Backspace will exit you back out. If everything does not go well - the screen goes blank, or is garbled - Ctrl-Alt-Backspace will end your session and you can modify the config file (see man Xorg) and check the log from Xorg's startup in /var/log/Xorg.0.log.

Once the configuration file is working satisfactorily, copy it to a location where Xorg will be able to see it by default.

# mkdir /etc/X11 (if it doesn't already exist)
# cp xorg.conf.new /etc/X11/xorg.conf
After this file is copied, you can use start Xorg with /usr/pkg/xorg/bin/startx and it will read your newly created configuration file.

3.2 Environment

The easiest way to have a usable desktop environment is to install one of the major desktop environments - KDE or Gnome.

# pkg_add http://www.pkgsrc-box.org/packages/stable/DragonFly-1.8/meta-pkgs/kdei-3.5.6.tgz


# pkg_add http://www.pkgsrc-box.org/packages/stable/DragonFly-1.8/meta-pkgs/gnome-devel-2.16.0.tgz

To enable KDE after installing, put 'startkde' into a file called .xinitrc in your home directory. Typing "startx" after that point (assuming you have X Windows installed and configured) will get you a graphical desktop.

# echo "startkde" > ~/.xinitrc

A similar procedure can enable the Gnome Desktop instead.

# echo "gnome-session" > ~/.xinitrc

4 Other resources

Contact the Documentation mailing list for comments, suggestions and questions about this document.