wanted: DOC-OP

[Tobias C. Rittweiler]

In my experience, you always have to toggle a few switches for each
project (name, version number, download url, etc), and I'd like to have
a general interface that hides the details, say

  (ASDF:OOS 'ASDF:DOC-OP :TARGET-DIR #P"..." ...)

(Original mailing list posting: http://thread.gmane.org/gmane.lisp.asdf.devel/343)

[Robert P. Goldman (rpgoldman)]

This would actually be

(asdf:oos 'asdf:doc-op <target-system-name> :target-dir ...)

that is, the keyword arguments come after the system name (as you'd expect for a normal CL function).

Note that all those arguments get swept up into the :original-initargs slot of the test-op instance, and then propagated through dependent ops.

What this means is that :original-initargs can be used as an arbitrary property list on which to stash attributes that will modulate the performance of any ASDF operation.

I have used this for a number of extensions to asdf operation classes.

[Tobias C. Rittweiler (tcr)]

Yes, sorry for the sloppiness on my part. ORIGINAL-INITARGS would be exactly
the facility I'd need.

There is another thing: my DOC-OP would be dependent on another system.
Surely, I can just (ASDF:LOAD-SYSTEM ...) inside my PERFORM method
specializing on DOC-OP -- though I guess that's what the :IN-ORDER-TO
argument is for.

(I just mention it for reasons of completeness.)

[Robert P. Goldman (rpgoldman)]

Right. I believe that something like

:in-order-to ((doc-op (load-op "albert")))

would do what you need there.

However, I also think we need a more general conditional construct for components of the system itself. Let's suppose we have a file that contains settings for the documentation. It would be nice if we could have something like:

((:file "doc-settings" :load-for-op (doc-op))

This also arises in handling test-op. It's typical to have a set of files that contain tests, and those files should not even be loaded except when you are performing a test-op (because they rely upon the test library which won't be loaded when you're just running the system). The only clean way I have found of doing this in existing ASDF is to push all of those files into a separate asdf system (say foo-tests for system foo), and then recording an :in-order-to ((test-op (test-op "foo-tests")))

I'd like it if there was a general way to specify components that are loaded in special circumstances like test-op and doc-op.

[Faré (fahree)]

You don't need that :load-for-op thingie. Just have albert depend on something else.

The problem you have there, however, is that ASDF lacks a mechanism to declare components that are not included by default, such as albert itself, or its dependencies. This could be "just" the matter of an inherited flag (true by default for backwards compatibility) that indicates whether a component is to be directly included when building the system. Note: in XCVB, you explicitly list the toplevel things you want to include in your build, and their dependencies are recursively included; what you leave out you can load independently later as part of other builds or using the master.

[Robert P. Goldman (rpgoldman)]

Can you clarify your response? I think we are actually agreeing with each other --- the load-for-op was my attempt to come up with a notation for (as you say) "components that are not included by default." The file "doc-settings" is intended to be just such a component, not loaded unless we are doing the doc-op.

My :load-for-op notation is stinky, but I think it's a capability that ASDF desperately needs.

I have done something like this in one-offs, using the :original-initargs on the operations, but that requires special purpose PERFORM methods. I never like those because they mean we no longer have a nice, declarative defsystem, but a mixture of declarative and procedural code. Also, there's the parallel disadvantage that they make anyone read the code look all over the place to figure out what exactly is going on with my system.

[Nikodemus Siivola (nikodemus)]

One way is to just write a PERFORM method

(defmethod perform ((o doc-op) (c (eql (find-system :my-system))))
  (operate 'load-op :foodoc)
  (funcall (intern "DOCUMENT-SYSTEM" :foodoc) :my-system))

However, regardless of details of how people are expected to write those ops, I think exporting a DOC-OP is uncontroversial, so I've confirmed this.

[Robert P. Goldman (rpgoldman)]

Any objections to adding a :doc-depends-on to defsystem? There's usually a system that must be loaded in order to generate the docs (and which need not be loaded otherwise).

Yes, I know one can write

(in-order-to (doc-op (load-op "albert")))

but that seems relatively long-winded....

A new question: do we assume that the doc-op by default requires a load-op?

[Tobias C. Rittweiler (tcr)]

"Robert P. Goldman" <email address hidden> writes:

> Any objections to adding a :doc-depends-on to defsystem? There's
> usually a system that must be loaded in order to generate the docs (and
> which need not be loaded otherwise).
>
> Yes, I know one can write
>
> (in-order-to (doc-op (load-op "albert")))
>
> but that seems relatively long-winded....

I don't like the abbreviation. People should get used to IN-ORDER-TO
because it's the thing they have to know about to keep system
definitions declarative -- which is important for static analyzing
tools.

And if you introduce a :DOC-DEPENDS-ON, then you should also introduce a
:TEST-DEPENDS-ON because TEST-OP most often has some dependency, too.

Personally, I'd rather change the syntax on IN-ORDER-TO to the following
because I find the current syntax not very mnemonic.

(IN-ORDER-TO DOC-OP :PERFORM (LOAD-OP "albert") (LOAD-OP "foo"))

That would not allow to specify several dependencies into one
IN-ORDER-TO clause -- which I actually think is a good thing, because
it's (imho anyway) cleaner to specify each in its own clause.

The change would be backwards-compatible.

  -T.

--
Diese Nachricht wurde auf Viren und andere gefaerliche Inhalte untersucht
und ist - aktuelle Virenscanner vorausgesetzt - sauber.
Freebits E-Mail Virus Scanner

[Faré (fahree)]

I'd like to add that the "ASDF" way, most compatible with the semantics of how ASDF handles targets, would be to add not a new operation, but a new system foo-doc. And if you insist on defining a doc-op operation, have it "just" load-op the foo-doc system.

[Robert P. Goldman (rpgoldman)]

I don't really think that's true. I think that "the ASDF way" here is just a reflection of the fact that ASDF is too lame to effectively let us store conditional information in system definitions.

So, for example, I have to set up a FOO-TEST system to make it possible for me to do testing, because there's no easy way to tell ASDF "these files are only tests and should only be loaded when testing."

But I don't think that's a feature! In particular, it is DEFINITELY not a feature if you make the user guess the name of the test system: "let me see, was it "foo-test"? "foo-tests"? "test-foo"?

Instead, we typically set things up so we have

;in-order-to (test-op (test-op "foo-test")))

so that we only need to type

(asdf:test-system "foo").

I think it would be A Good Thing if it were analogously possible for users to just type

(asdf:document-system "foo")

[Faré (fahree)]

I'd like to mark this as "Won't fix".

Now that there is a functional defsystem-depends-on, this could all be done in an ASDF extension. And yes, if the extension is vastly successful, it could be folded back into ASDF itself, like ASDF-Bundle was before it.

But until I see a widely adopted extension that provides said DOC-OP, I am not going to add anything to ASDF itself.

[Faré (fahree)]

Marking as Won't Fix. At least not for now, at least not by me.

I encourage those who care to develop a suitable ASDF extension.