Anaconda/SourceOverview

From FedoraProject

< Anaconda(Difference between revisions)
Jump to: navigation, search
m (corrected typo interal --> interval)
m (Source Overview: add pointer to main article)
 
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{autolang|base=yes}}
 
<!-- page was renamed from AnacondaSourceOverview
 
<!-- page was renamed from AnacondaSourceOverview
 
-->
 
-->
 
= Source Overview =
 
= Source Overview =
  
anaconda has a lot of source, and this can be a little intimidating at first.  It can be difficult to figure out where to even start looking when you're trying to track a problem down.  This guide is meant as a very high level overview of the various groups of source files and what sorts of things they cover.  It's not incredibly detailed, and some source files don't want to fit into categories.  Lots of pieces of functionality are spread out across multiple files.
+
anaconda has a lot of source, and this can be a little intimidating at first.  It can be difficult to figure out where to even start looking when you're trying to track a problem down.  This guide is meant as a very high level overview of the various groups of source files and what sorts of things they cover.  It's not incredibly detailed, and some source files don't want to fit into categories.  Lots of pieces of functionality are spread out across multiple files.  The main article about [[Anaconda]] describes where to obtain the source code, which is presently maintained in a 'git' repository.
  
 
== Interface ==
 
== Interface ==
cmdline.py<BR>
+
* pyanaconda/ui/gui/
gui.py<BR>
+
* pyanaconda/ui/tui/
text.py
+
  
These files handle the user interfaces.  There are three interfaces supported by anaconda:  graphical, text, and the command line mode.  Each is implemented by its own python file that contains classes for drawing various types of windows and so forth.
+
These are the primary UI files for the interfaces supported by anaconda:  graphical, text, and command line (which is really just a special form of text).  Each is implemented by its own directory.  For the graphical installer, the glade interface files are in the same location.  For the text installer, this also includes the code required to do line-oriented input/output.  There is a well-defined API here allowing for both adding additional interfaces and extending the existing interfaces with new screens.
  
iw/<BR>
+
* pyanaconda/ui/__init__.py
textw/<BR>
+
* pyanaconda/ui/common.py
ui/
+
* pyanaconda/ui/communication.py
 +
* pyanaconda/ui/lib/
  
The iw/ directory contains python files for the graphical interface screens.  The textw/ directory contains python files for the text interface screensThe ui/ directory contains glade interface description files that are also needed for graphical mode.  In general, we are trying to move towards more glade files whenever possible.
+
These files and directories contain code common to all supported interfaces.  The first two files contain mostly base classes with code common to both the GUI and TUIcommunication.py is a small file containing constants and methods for communicating between objects within the UI.
  
dispatch.py
+
* pyanaconda/vnc.py
 
+
The dispatcher is a state machine that controls moving between steps in the installer.  It knows which screen to go to when a Next or Back button is clicked, and knows which steps should be skipped depending on a variety of settings.  Each mode of  installation provides its own set of steps that should be skipped.
+
 
+
vnc.py
+
  
 
This file controls setting up VNC for when it is requested during installation.  Afterwards, installs proceed in graphical mode.
 
This file controls setting up VNC for when it is requested during installation.  Afterwards, installs proceed in graphical mode.
  
mini-wm.c<BR>
+
== Custom Widgets ==
xutils.c
+
The anaconda GUI makes use of some custom widgets.  Everything listed below either implements these widgets or is needed for support.
  
These files provide the window manager that runs during graphical installations.
+
* widgets/data/
  
== Partitioning ==
+
This directory contains images used by the timezone map widget.
dmraid.py<BR>
+
gpt.py<BR>
+
iscsi.py<BR>
+
lvm.py<BR>
+
raid.py<BR>
+
zfcp.py<BR>
+
  
These files handle probing, configuring, starting, and stopping the advanced storage devices that are supported by anaconda.  LVM and RAID are fairly widely used (LVM is the default partitioning), while the others are much less so.
+
* widgets/glade/
 +
* widgets/python/
  
lvmErrors.py<BR>
+
These two directories are support files. The glade subdirectory contains code to help glade understand these new widgets so they can be used in the interface builder.  The python subdirectory contains code to allow using the widgets through gobject-introspection in a more native Python manner.
partErrors.py
+
  
These files define exception classes for problems that can occur during partitioning.
+
* widgets/src
  
partIntfHelpers.py
+
And then this is the code that implements the widgets themselves.  There is one header and one source code file per widget class.
  
This file contains methods that are used for error checking, input validation, and displaying error messages.  The graphical and text interfaces make use of it.
+
== Partitioning ==
 +
All partitioning code is now contained in the python-blivet package, which we also work on.
  
autopart.py<BR>
+
== Bootloader ==
cryptodev.py<BR>
+
* pyanaconda/bootloader.py
fsset.py<BR>
+
gptsync/<BR>
+
partRequests.py<BR>
+
partedUtils.py<BR>
+
partitioning.py<BR>
+
partitions.py
+
  
This group of files implements the partitioning logic.  It converts the user's selections into requests, then into entries, and eventually makes partitions on diskIt also controls making filesystems, writing out the /etc/fstab file, labelling devices, and doing automatic partitioning (which is the default).  Partitions are created on disk by using the pyparted package.
+
This file controls configuring and writing out the bootloader to the installed systemEach type of machine has its own bootloader quirks (what types of devices and filesystems are supported by the bootloader, the syntax of the config file, etc). and therefore has its own classThis file additionally handles pulling together kernel command line arguments.
  
 
== Configuration ==
 
== Configuration ==
bootloader.py<BR>
+
* pyanaconda/desktop.py
desktop.py<BR>
+
* pyanaconda/keyboard.py
firewall.py<BR>
+
* pyanaconda/localization.py
instdata.py<BR>
+
* pyanaconda/network.py
language.py<BR>
+
* pyanaconda/ntp.py
network.py<BR>
+
* pyanaconda/timezone.py
security.py<BR>
+
* pyanaconda/users.py
timezone.py<BR>
+
users.py<BR>
+
xsetup.py
+
  
 
These files hold the configuration settings that are either entered through the interface or through kickstart.  To some extent they affect the installation (for instance, the language and keyboard settings are used in anaconda).  However, the main purpose is to write these out to the installed system at the end of installation.
 
These files hold the configuration settings that are either entered through the interface or through kickstart.  To some extent they affect the installation (for instance, the language and keyboard settings are used in anaconda).  However, the main purpose is to write these out to the installed system at the end of installation.
  
 
== Package Installation ==
 
== Package Installation ==
backend.py<BR>
+
* pyanaconda/packaging/
image.py<BR>
+
* scripts/anaconda-yum
sortedtransaction.py<BR>
+
whiteout.py<BR>
+
yuminstall.py
+
  
These files control package installation.  anaconda allows for multiple package installation backends, though the only real one in the tree uses yum.  Each backend provides methods for selecting groups and packages, removing groups and packages, writing out configuration settings, and so forth.  For fixing loops in package dependencies, we use the whiteout which explains how to correctly break loops.
+
These files control the installation of files in some format to the system.  anaconda allows for multiple installation backends, though the most commonly used are yumpayload.py and livepayload.py.  Each backend provides methods for selecting and removing environments, groups, and packages; configuring repos for use during and after installation; reporting progress; and so forth.  There is a well-defined API here allowing for adding additional backends.
 +
 
 +
The anaconda-yum script is used to work around problems with anaconda, yum, urlgrabber, and threads.  This script does the actual installation of packages.  It is also Python.
  
 
== Installation Classes ==
 
== Installation Classes ==
installclass.py<BR>
+
* pyanaconda/installclass.py
installclasses/<BR>
+
* pyanaconda/installclasses/
product.py
+
* pyanaconda/product.py
  
 
Installation classes define settings that form a sort of installation profile.  This includes steps to show and skip, product names, installation method, enabled repositories, configuration settings, and so forth.  We primarily use it to create a difference between Fedora and RHEL installs.  Other projects or ISVs could define their own installation classes for their own defaults.
 
Installation classes define settings that form a sort of installation profile.  This includes steps to show and skip, product names, installation method, enabled repositories, configuration settings, and so forth.  We primarily use it to create a difference between Fedora and RHEL installs.  Other projects or ISVs could define their own installation classes for their own defaults.
  
 
== Special Modes ==
 
== Special Modes ==
kickstart.py
+
* pyanaconda/kickstart.py
  
[wiki:Self:AnacondaKickstart Kickstart] is a way of automating installations by providing anaconda with a file that contains all the data that the user would have to provide via the UI.  This file is an interface between the parser in the pykickstart package and the anaconda intervalsIt primarily provides a way of saving the settings in the places anaconda expects.
+
[[Anaconda/Kickstart| Kickstart]] is a way of automating installations by providing anaconda with a file that contains all the data that the user would have to provide via the UI.  This file is an interface between the parser in the pykickstart package and the anaconda internalsNow that the UI now constructs a kickstart data object in memory, this file also handles certain execution tasks as well.
  
livecd.py<BR>
+
* data/icons/
liveinst/
+
* data/liveinst/
  
These files implement installation from the live CD.  They provide, a special installation method, a special package installation backend, and some files needed to launch the installer from the live CD's desktop.
+
These files implement installation from the live CD.  They provide some files needed to launch the installer from the live CD's desktop.  The actual live installation is handled by the appropriate packaging backend.
  
rescue.py<BR>
+
* pyanaconda/constants_text.py
upgrade.py
+
* pyanaconda/installinterfacebase.py
 +
* pyanaconda/rescue.py
 +
* pyanaconda/text.py
  
These files provide methods specific to rescue mode and upgrades.
+
These files provide the rescue mode.
 +
 
 +
== Error Handling ==
 +
* pyanaconda/errors.py
 +
* pyanaconda/exception.py
 +
 
 +
These files control all the error reporting for anaconda.  errors.py, in combination with the UI, controls displaying errors that the user can do something about or at least that anaconda can anticipate.  This is the central location for error messages.  exception.py controls display of errors that anaconda cannot anticipate - basically, this is where unhandled exceptions get handled.  This is also where anaconda interfaces with libreport to report issues to bugzilla.
 +
 
 +
== Installation Control Library ==
 +
* pyanaconda/install.py
 +
* pyanaconda/progress.py
 +
* pyanaconda/queue.py
 +
* pyanaconda/threads.py
 +
 
 +
This is a loose collection of important files.  install.py actually performs the installation steps, which just consists of calling out to methods throughout kickstart, anaconda, and python-blivet.  progress.py provides a way for install.py and the packaging backends to communicate with the UI for moving the progress bar and displaying messages.  queue.py is a support file that constructs communications queues, like those used in progress.py and communication.py.  Finally, threads.py handles creating and managing threads, which anaconda now extensively uses for running tasks in the background while still allowing the UI to update.
  
 
== Library ==
 
== Library ==
anaconda_log.py<BR>
+
* pyanaconda/__init__.py
constants.py<BR>
+
* pyanaconda/addons.py
exception.py<BR>
+
* pyanaconda/anaconda_log.py
flags.py<BR>
+
* pyanaconda/anaconda_optparse.py
floppy.py<BR>
+
* pyanaconda/constants.py
isys/<BR>
+
* pyanaconda/flags.py
iutil.py<BR>
+
* pyanaconda/geoloc.py
packages.py<BR>
+
* pyanaconda/i18n.py
syslogd.py<BR>
+
* pyanaconda/image.py
timer.py
+
* pyanaconda/indexed_dict.py
 +
* pyanaconda/isys/
 +
* pyanaconda/iutil.py
 +
* pyanaconda/nm.py
 +
* pyanaconda/safe_dbus.py
 +
* pyanaconda/simpleconfig.py
 +
* pyanaconda/sitecustoimze.py
  
These files provide a variety of miscellaneous methods that are used throughout the installer.  These functions include the logging framework, hardware probing, device node management, process control, handling exceptions, and other tasks.  They also contain methods that just don't fit anywhere else.
+
These files provide a variety of miscellaneous methods that are used throughout the installer.  These functions include the logging framework, finding the user's location via geolocation, looking up information about attached optical installation media, communicating with NetworkManager, and many other tasks.  They also contain methods that just don't fit anywhere else.
  
 
== The Main Program ==
 
== The Main Program ==
anaconda
+
* anaconda
 +
 
 +
This is the main anaconda program that gets called via systemd at the end of system bootup.  It handles lots of environment setup, enables updates if they exist, reads any kickstart file, sets up VNC, and other tasks.  When all this is done, it hands control over to the UI which in turn drives the rest of installation.
 +
 
 +
== Startup ==
 +
* data/systemd/
 +
* dracut/
 +
 
 +
Someone with a better understanding of things than me (clumens) needs to fill this section in.
 +
 
 +
== Miscellaneous ==
 +
 
 +
* data/interactive-defaults.ks
 +
* data/post-scripts/
 +
 
 +
Given that anaconda is internally building a kickstart file via the UI and then executing it, certain installation tasks are more easily implemented as kickstart scripts.  These do that.  interactive-defaults.ks is a kickstart file pulled in at the beginning of an interactive, non-kickstart installation that contains certain default settings for the UI.
 +
 
 +
* scripts/anaconda-cleanup
 +
 
 +
* scripts/instperf
 +
* scripts/instperf.p
 +
 
 +
The former is a program that monitors memory usage during installation and writes out /tmp/memory.dat with this information.  The latter is a gnuplot script that interprets that file and generates a graph.  We use this to identify spikes in memory usage.
 +
 
 +
* scripts/makebumpver
 +
 
 +
* scripts/makeupdates
 +
 
 +
makeupdates is a tool for creating [[Anaconda/Updates|updates images]] for testing anaconda fixes. You can call it with reference to a particular tag or commit and it will build an image containing all the changes to the tree since that point.
  
This is the main anaconda program that gets called from the loader.  It handles lots of environment setup, enables updates if they exist, reads any kickstart file, sets up VNC, and other tasks.  When all this is done, it hands control over to the dispatcher which deals with the rest of the installation process.
+
* scripts/restart-anaconda
  
== Image Building ==
+
* utils/dd/
bootdisk/<BR>
+
command-stubs/<BR>
+
scripts/<BR>
+
stubs/<BR>
+
utils/<BR>
+
wlite/
+
  
These directories contain code that controls how the installation
+
* utils/handle-sshpw
environment is made.  This includes creating the initial ramdisk and the
+
stage2 images, adding very basic versions of certain needed commands,
+
splitting the installation tree into media-sized chunks, and other
+
miscellaneous tasks.
+
  
== Loader ==
+
* utils/logpicker
loader2/
+
* utils/log_picker/
  
Coming soon.
+
logpicker is a tool for sending anaconda logs and other useful diagnostic information out of the installation environment in various ways (scp, ftp, Bugzilla...). It has some overlap with the graphical process that lets you submit a bug report when anaconda crashes. It has not been updated since being committed in 2010 and may be somewhat bitrotten.
  
 
----
 
----
 
[[Category:Anaconda]]
 
[[Category:Anaconda]]

Latest revision as of 20:51, 16 May 2013

Contents

[edit] Source Overview

anaconda has a lot of source, and this can be a little intimidating at first. It can be difficult to figure out where to even start looking when you're trying to track a problem down. This guide is meant as a very high level overview of the various groups of source files and what sorts of things they cover. It's not incredibly detailed, and some source files don't want to fit into categories. Lots of pieces of functionality are spread out across multiple files. The main article about Anaconda describes where to obtain the source code, which is presently maintained in a 'git' repository.

[edit] Interface

  • pyanaconda/ui/gui/
  • pyanaconda/ui/tui/

These are the primary UI files for the interfaces supported by anaconda: graphical, text, and command line (which is really just a special form of text). Each is implemented by its own directory. For the graphical installer, the glade interface files are in the same location. For the text installer, this also includes the code required to do line-oriented input/output. There is a well-defined API here allowing for both adding additional interfaces and extending the existing interfaces with new screens.

  • pyanaconda/ui/__init__.py
  • pyanaconda/ui/common.py
  • pyanaconda/ui/communication.py
  • pyanaconda/ui/lib/

These files and directories contain code common to all supported interfaces. The first two files contain mostly base classes with code common to both the GUI and TUI. communication.py is a small file containing constants and methods for communicating between objects within the UI.

  • pyanaconda/vnc.py

This file controls setting up VNC for when it is requested during installation. Afterwards, installs proceed in graphical mode.

[edit] Custom Widgets

The anaconda GUI makes use of some custom widgets. Everything listed below either implements these widgets or is needed for support.

  • widgets/data/

This directory contains images used by the timezone map widget.

  • widgets/glade/
  • widgets/python/

These two directories are support files. The glade subdirectory contains code to help glade understand these new widgets so they can be used in the interface builder. The python subdirectory contains code to allow using the widgets through gobject-introspection in a more native Python manner.

  • widgets/src

And then this is the code that implements the widgets themselves. There is one header and one source code file per widget class.

[edit] Partitioning

All partitioning code is now contained in the python-blivet package, which we also work on.

[edit] Bootloader

  • pyanaconda/bootloader.py

This file controls configuring and writing out the bootloader to the installed system. Each type of machine has its own bootloader quirks (what types of devices and filesystems are supported by the bootloader, the syntax of the config file, etc). and therefore has its own class. This file additionally handles pulling together kernel command line arguments.

[edit] Configuration

  • pyanaconda/desktop.py
  • pyanaconda/keyboard.py
  • pyanaconda/localization.py
  • pyanaconda/network.py
  • pyanaconda/ntp.py
  • pyanaconda/timezone.py
  • pyanaconda/users.py

These files hold the configuration settings that are either entered through the interface or through kickstart. To some extent they affect the installation (for instance, the language and keyboard settings are used in anaconda). However, the main purpose is to write these out to the installed system at the end of installation.

[edit] Package Installation

  • pyanaconda/packaging/
  • scripts/anaconda-yum

These files control the installation of files in some format to the system. anaconda allows for multiple installation backends, though the most commonly used are yumpayload.py and livepayload.py. Each backend provides methods for selecting and removing environments, groups, and packages; configuring repos for use during and after installation; reporting progress; and so forth. There is a well-defined API here allowing for adding additional backends.

The anaconda-yum script is used to work around problems with anaconda, yum, urlgrabber, and threads. This script does the actual installation of packages. It is also Python.

[edit] Installation Classes

  • pyanaconda/installclass.py
  • pyanaconda/installclasses/
  • pyanaconda/product.py

Installation classes define settings that form a sort of installation profile. This includes steps to show and skip, product names, installation method, enabled repositories, configuration settings, and so forth. We primarily use it to create a difference between Fedora and RHEL installs. Other projects or ISVs could define their own installation classes for their own defaults.

[edit] Special Modes

  • pyanaconda/kickstart.py

Kickstart is a way of automating installations by providing anaconda with a file that contains all the data that the user would have to provide via the UI. This file is an interface between the parser in the pykickstart package and the anaconda internals. Now that the UI now constructs a kickstart data object in memory, this file also handles certain execution tasks as well.

  • data/icons/
  • data/liveinst/

These files implement installation from the live CD. They provide some files needed to launch the installer from the live CD's desktop. The actual live installation is handled by the appropriate packaging backend.

  • pyanaconda/constants_text.py
  • pyanaconda/installinterfacebase.py
  • pyanaconda/rescue.py
  • pyanaconda/text.py

These files provide the rescue mode.

[edit] Error Handling

  • pyanaconda/errors.py
  • pyanaconda/exception.py

These files control all the error reporting for anaconda. errors.py, in combination with the UI, controls displaying errors that the user can do something about or at least that anaconda can anticipate. This is the central location for error messages. exception.py controls display of errors that anaconda cannot anticipate - basically, this is where unhandled exceptions get handled. This is also where anaconda interfaces with libreport to report issues to bugzilla.

[edit] Installation Control Library

  • pyanaconda/install.py
  • pyanaconda/progress.py
  • pyanaconda/queue.py
  • pyanaconda/threads.py

This is a loose collection of important files. install.py actually performs the installation steps, which just consists of calling out to methods throughout kickstart, anaconda, and python-blivet. progress.py provides a way for install.py and the packaging backends to communicate with the UI for moving the progress bar and displaying messages. queue.py is a support file that constructs communications queues, like those used in progress.py and communication.py. Finally, threads.py handles creating and managing threads, which anaconda now extensively uses for running tasks in the background while still allowing the UI to update.

[edit] Library

  • pyanaconda/__init__.py
  • pyanaconda/addons.py
  • pyanaconda/anaconda_log.py
  • pyanaconda/anaconda_optparse.py
  • pyanaconda/constants.py
  • pyanaconda/flags.py
  • pyanaconda/geoloc.py
  • pyanaconda/i18n.py
  • pyanaconda/image.py
  • pyanaconda/indexed_dict.py
  • pyanaconda/isys/
  • pyanaconda/iutil.py
  • pyanaconda/nm.py
  • pyanaconda/safe_dbus.py
  • pyanaconda/simpleconfig.py
  • pyanaconda/sitecustoimze.py

These files provide a variety of miscellaneous methods that are used throughout the installer. These functions include the logging framework, finding the user's location via geolocation, looking up information about attached optical installation media, communicating with NetworkManager, and many other tasks. They also contain methods that just don't fit anywhere else.

[edit] The Main Program

  • anaconda

This is the main anaconda program that gets called via systemd at the end of system bootup. It handles lots of environment setup, enables updates if they exist, reads any kickstart file, sets up VNC, and other tasks. When all this is done, it hands control over to the UI which in turn drives the rest of installation.

[edit] Startup

  • data/systemd/
  • dracut/

Someone with a better understanding of things than me (clumens) needs to fill this section in.

[edit] Miscellaneous

  • data/interactive-defaults.ks
  • data/post-scripts/

Given that anaconda is internally building a kickstart file via the UI and then executing it, certain installation tasks are more easily implemented as kickstart scripts. These do that. interactive-defaults.ks is a kickstart file pulled in at the beginning of an interactive, non-kickstart installation that contains certain default settings for the UI.

  • scripts/anaconda-cleanup
  • scripts/instperf
  • scripts/instperf.p

The former is a program that monitors memory usage during installation and writes out /tmp/memory.dat with this information. The latter is a gnuplot script that interprets that file and generates a graph. We use this to identify spikes in memory usage.

  • scripts/makebumpver
  • scripts/makeupdates

makeupdates is a tool for creating updates images for testing anaconda fixes. You can call it with reference to a particular tag or commit and it will build an image containing all the changes to the tree since that point.

  • scripts/restart-anaconda
  • utils/dd/
  • utils/handle-sshpw
  • utils/logpicker
  • utils/log_picker/

logpicker is a tool for sending anaconda logs and other useful diagnostic information out of the installation environment in various ways (scp, ftp, Bugzilla...). It has some overlap with the graphical process that lets you submit a bug report when anaconda crashes. It has not been updated since being committed in 2010 and may be somewhat bitrotten.