<--- Cast Home #### -->

Sorcery

D. Dispel

While it might certainly be fun to cast spells left and right and empower your Source Mage computer, it is only half the story. There will come a time when you'd want to keep your SMGL system slim and healthy, by cutting down on the unnecessary files that may be clogging up your computer. Or perhaps you're just a neat freak and can't sleep over the fact that there might be unused programs taking up space that could be used for some other higher purpose. Whatever the reason, dispel is the tool for you.

In it's most basic form, dispel is called like this: dispel <spell>

dispel is cast's undoing. It uninstalls a spell that has been cast by deleting the files that were installed during casting, based on the installation log file created for that spell in the /var/log/sorcery/log/ directory. However, dispel doesn't annihilate all traces of the spell. In order to make it possible to resurrect the spell later on, the spell's install cache tarbell is left intact in the /var/cache/sorcery/ directory (see discussion on cast for details about these two files and resurrecting).

1. Basic options

Like cast, dispel is more powerful than it seems from it's basic syntax. dispel has a couple of options that I conceptually group into three. This first group comprises the most basic or commonly used options.

-e or --exile
This option will mark a dispelled spell as exiled, banishing it from your system forever! Ok, maybe not forever. But it does prevent that particular spell from being casted again, whether by explicitly casting the exiled spell or by casting another spell that depends on the exiled spell. The effect of sending a spell off to exile is that it will not be cast during an update and that anything that depends on it cannot be cast.

dispel --exile <spell>

NOTE: As of this writing, the exile option for dispel only works when using the full word option --exile. It fails to exile a spell if only -e is used. This only happens if dispel is run as a normal user. If run from a root prompt or using su -c or sudo, both -e and --exile behave correctly.

You can offer a spell some clemency by removing the exiled mark using the command:

sorcery unexile <spell>;

To see a list of exiled spells, use the command:

gaze show-exiled;

-d or --downgrade
This option does two things: it dispels the current version of the spell installed and it resurrects the spell using the version specified in the command:

dispel -d <spell> <version>

Note that dispel -d can only resurrect the version indicated. The install cache for the particular version must exist in the /var/cache/sorcery/ directory, otherwise the command fails and nothing is dispelled.

HINT: dispel -d can work as an "upgrade" too. The version that must be specified doesn't need to be lower than the currently installed version. You can use it to resurrect a higher version of a spell as well.

2. Dependency Following options

Here comes the fun part, the part that showcases dispel's power. Just as cast resolves dependencies when trying to install packages, dispel likewise walks through dependencies in an attempt to clean up the debris left in the wake of the dispelled spell. Unlike cast, however, dispel does not perform dependency following by default, but it's as simple as adding an option or two to the command. But first, some definition of terms to help us understand the process.

(For the purpose of illustration, we will be using Blender and Wings 3D. The following explanations will be based on this diagram)

a. Definition of Terms

Child
This is a spell on which the current spell depends on. In other words, the child is a dependency of the spell. For example, in:

dispel wings3d

esdl is a child of wings3d, since it is a required dependency of wings3d. yafray is also a child of wings3d, although it is only an optional dependency.

Parent
This is a spell that depends on the current spell being dispelled. The spell in question is a dependency, required or optional, of the parent. For example, in:

dispel yafray

blender is the parent of yafray, since blender (optionally) depends on yafray. And in:

dispel scons

Both blender and yafray are parents of scons because both depend on scons.

In the case of an optional dependency, a spell only becomes a parent of a spell if the optional dependency on the current spell has been enabled. So if wings3d's optional dependency yafray wasn't enabled, wings3d does not become yafray's parent, even if both spells are installed.

Now there are two kinds of children: orphans and non-orphans.

Orphan
An orphan is a kind of child on which no other spell depends on except the current spell that is about to be dispelled. It is not a dependency of any other spell. After the current spell has been dispelled, this child will have no other spell that depends on it. It has no other parent. It is orphaned.

Non-orphan
A non-orphan is a child that has other parents other than the current spell. It is a dependency of other spells. After the current spell has been removed, this child will still be a child of other spells.

Let's say we try to

dispel wings3d

In this case, both esdl and an OPENGL provider (see discussion of providers in the cast page) become orphans. They are children of wings3d that are not needed by any other spell except wings3d On the other hand, yafray is both an optional dependency of wings3d and blender. Even if wings3d is dispelled, yafray is still needed by blender. yafray still has a parent, so it is a non-orphan. It is safe to dispel orphans, since no other spell depend on them. Dispelling non-orphans, however, can have consequences, such as breaking its parents.

Broken Parent
A broken parent has a dependency on the dispelled spell, whether the dependency is required or optional. If the parent requires this spell to function at all, it is totally broken. There is no other alternative but to dispel the parent as well.

Repairable Parent
A repairable parent is a type of broken parent that only has an optional dependency on the current spell. The spell is only needed for an optional feature to work. The parent can continue functioning without the spell and without the optional feature, but it has to be recast in order to remove the optional dependency.

b. The options

Now that we've got the terms down, let's see the options that dispel has for children and parents. Each of these options one of four parameters (collectively labelled as "quad-opt") that indicate what action it has to take for the particular child or parent. The four parameters are:

--orphan <quad-opt>
Indicates what action to take for a new orphan of the dispelled spell. It only asks about orphans and skips non-orphans.

--non-orphan <quad-opt>;
Indicates what action to take for a new non-orphan of the spell that is being dispelled. It only asks about non-orphans and doesn't ask about orphans. Use with caution, as it can cause broken parents.

--child <quad-opt>;
Indicates what action to take for any kind of child of the current spell. It will indicate whether the child is an orphan or a non-orphan before asking or taking action. Use with the same caution, as dispelling a non-orphan can cause broken parents

--dispel-parent <quad-opt>;
Indicates the action to be taken for broken parents, whether totally broken or repairable, of the spell being removed.

--recast-parent <quad-opt>;
Indicates the action to be taken for a repairable parent of the current spell. Since the parent only has an optional dependency on the dispelled spell, it is possible to repair the parent by simply recasting it and removing the optional dependency (thereby removing the corresponding optional feature).

c. The flow

As with cast, dispel follows a certain step-by-step process in stepping through the current spell's dependencies, depending on the dependency following options indicated. The basic rule of thumb is "Step down before stepping up", that is, step through the dispelled spell's children before even looking at its parents.

Note that dispel does not look at/step through any kind of child or parent unless the option for it is included, so dispel won't even bother with parents (or tell you if you have broken ones) even if you have included options for children. Also, dispel will only walk through the children and parents of dispelled spells. It will, of course, leave other spells undisturbed.

As an example, let's use Blender as our guinea pig:

dispe --child ask-no --dispel-parent ask-no blenderl

Which basically means "dispel blender, walk through its children, both orphans and non-orphans, asking me whether I want to dispel them (with a default answer of "no"), and walk through the broken parents of dispelled spells, asking whether I want to dispel them (with a default answer of "no").

This diagram illustrates the flow of the process. Just keep in mind that the flow depends heavily on what actions you take (to dispel or not to dispel)

The explanation for the steps are as follows:

  1. Dispel blender and start walking through its children
  2. We reach scons. scons is not an orphan (yafray depends on it too), but we're asked whether we want to dispel it. Let's say "y" for now. Ssconsis dispelled and we walk through the rest of blender's children (all answering "n", including yafray)
  3. Since blender has no parents, we turn our attention to the latest dispelled spell, which is scons. We walk through scons' only child and (for the sake of world peace) choose not to dispel it.
  4. scons has a parent, so --dispel-parent kicks into action. Since yafray has a hard dependency on scons, there really is no other choice than to dispel it (--recast-parent won't work). So we dispel yafray.
  5. yafray is the the most recent dispelled spell, so now we walk through yafray's children. We aallanswer "n".
  6. yafray has a parent too, so again we are asked whether we want wings3d to be dispelled. yafray is just an optional dependency of wings3d, so it's possible to repair wings3d, but since we only indicated --dispel-parent, the only action available to us is to dispel it. However, if we added --recast-parent, we will be first given the option to recast wings3d without yafray.
  7. Since wings3d was the recently dispelled spell, we walk through its children. esdl is now an orphan, so we can safely dispel it.
  8. Next we walk through esdl's children, and, since erlang is now an orphan, we can also safely dispel it. There are no more children or parents to be considered.

Thus ends the dispel.

d. Sorcery makes it easy

You might get tired of always typing in the children/parent options, so Sorcery has a way to make it more convenient. Launch the sorcery menu by entering the command

sorcery

Then proceed to the Option menu and then the Dependency Following options. Here you can set the default actions to be taken for orphans, non-orphans, repairable broken parents, and broken parents in general. Once you have set these default actions, you can include any of these options to the dispel command:

--user-deps
Use the default actions for all children and parents specified in the sorcery options for dependency following. This is equivalent to using both --user-child-deps and --user-parent-deps at the same time

--user-child-deps
Use the default actions for children, both orphans and non-orphans, specified in the sorcery options for dependency following.

--user-parent-deps
Use the default actions for repairable and broken parents specified in the sorcery options for dependency following.

3. Advanced options

These options are probably rarely used and should only be used if you absolutely know what you are doing, hence I have categorized them as advanced options (Ok, I actually call them the "no" options since they all begin with a "no").

--notriggers
Turns of the sorcery's trigger mechanism for the duration of the dispel. No spells will be automatically rrecastor dispelled if a trigger has been defined for the dispelled spell

--noreap
Do not remove the files installed by the spell

--nosustain
turns off sorcery's safeguard over spells vital to your system (defined in /var/lib/sorcery/sustained). Use with extreme caution.

--no-reap-depends
Do not remove ddependency information of the dispelled spell. Again, use with extreme caution.

4. Tips

Here are some easy to remember tips for making dispel your best friend:

Now you can go crazy casting spells, knowing that you can always undo them with dispel.

<--- Cast Home #### -->
std::cout
This is a standard output box. It will occassionally contain announcement, news, quotes, ramblings, or anything under the sun.

Hyperlinks