From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Andy Wingo Newsgroups: gmane.lisp.guile.bugs Subject: bug#10327: Please document include and include-from-path Date: Fri, 27 Jan 2012 16:31:31 +0100 Message-ID: <87aa59go18.fsf@pobox.com> References: <87ehvu975c.fsf@Kagami.home> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1327678369 25487 80.91.229.12 (27 Jan 2012 15:32:49 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 27 Jan 2012 15:32:49 +0000 (UTC) Cc: Ian Hulin , 10327-done@debbugs.gnu.org To: Ian Price Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Fri Jan 27 16:32:45 2012 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1RqnnA-0007wT-Pz for guile-bugs@m.gmane.org; Fri, 27 Jan 2012 16:32:45 +0100 Original-Received: from localhost ([::1]:53475 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RqnnA-0002g5-9t for guile-bugs@m.gmane.org; Fri, 27 Jan 2012 10:32:44 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:42717) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rqnmy-0002ef-LU for bug-guile@gnu.org; Fri, 27 Jan 2012 10:32:41 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Rqnmr-0005UV-SP for bug-guile@gnu.org; Fri, 27 Jan 2012 10:32:32 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:41517) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rqnmr-0005UE-Hi for bug-guile@gnu.org; Fri, 27 Jan 2012 10:32:25 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1RqnnT-0005Se-37 for bug-guile@gnu.org; Fri, 27 Jan 2012 10:33:03 -0500 Resent-From: Andy Wingo Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: bug-guile@gnu.org Resent-Date: Fri, 27 Jan 2012 15:33:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: cc-closed 10327 X-GNU-PR-Package: guile X-GNU-PR-Keywords: Mail-Followup-To: 10327@debbugs.gnu.org, wingo@pobox.com Original-Received: via spool by 10327-done@debbugs.gnu.org id=D10327.132767834020938 (code D ref 10327); Fri, 27 Jan 2012 15:33:02 +0000 Original-Received: (at 10327-done) by debbugs.gnu.org; 27 Jan 2012 15:32:20 +0000 Original-Received: from localhost ([127.0.0.1]:46903 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1Rqnml-0005Rf-H4 for submit@debbugs.gnu.org; Fri, 27 Jan 2012 10:32:19 -0500 Original-Received: from a-pb-sasl-sd.pobox.com ([74.115.168.62]:34570 helo=sasl.smtp.pobox.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1Rqnmg-0005RV-VR for 10327-done@debbugs.gnu.org; Fri, 27 Jan 2012 10:32:16 -0500 Original-Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id 3DEEB905F; Fri, 27 Jan 2012 10:31:36 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=IfHSyvjxpbhonWjGZeA5vt85BZ8=; b=jbxl0Q mod+J5CkdmpYujnYu2yxzY0gfczfUk3xAHpPu5bfa3+TX+5Hqi/mdItEt2zoLfWf EivzZLRHR+mW+VCZ/Ja17hAuippw6GetanXtkmwSJSjeJGavgC0PUbgeAvV8hINH 1GKNP0qx3QSZ5QQxInviX04HLZsLw/c56o7E8= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; q=dns; s=sasl; b=ULGfZqcurhWeWqg7m9PB1J8OEPAuo7aD nq56YlvlxIUjWk+2g3kl6f/NYgL0B26e4o83HVN/52k8sfq3mYhdyzDBNXhC5VRV bcPzD04NCv5b6zgQd+zuOU6KEU0SWkxqd6iKh90xoNZMIscPA4uSm/W3xztk31Od XyxE3LDjMuE= Original-Received: from a-pb-sasl-sd.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id 36DFD905E; Fri, 27 Jan 2012 10:31:36 -0500 (EST) Original-Received: from badger (unknown [90.164.198.39]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTPSA id 71DC9905D; Fri, 27 Jan 2012 10:31:35 -0500 (EST) In-Reply-To: <87ehvu975c.fsf@Kagami.home> (Ian Price's message of "Fri, 23 Dec 2011 23:53:51 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux) X-Pobox-Relay-ID: FF5E0BC4-48FB-11E1-8715-65B1DE995924-02397024!a-pb-sasl-sd.pobox.com X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.bugs:6095 Archived-At: Hello Ian & Ian :) Thanks for the report. I added some extensive docs. 6.17.11 Local Inclusion ----------------------- This section has discussed various means of linking Scheme code together: fundamentally, loading up files at run-time using `load' and `load-compiled'. Guile provides another option to compose parts of programs together at expansion-time instead of at run-time. -- Scheme Syntax: include file-name Open FILE-NAME, at expansion-time, and read the Scheme forms that it contains, splicing them into the location of the `include', within a `begin'. If you are a C programmer, if `load' in Scheme is like `dlopen' in C, consider `include' to be like the C preprocessor's `#include'. When you use `include', it is as if the contents of the included file were typed in instead of the `include' form. Because the code is included at compile-time, it is available to the macroexpander. Syntax definitions in the included file are available to later code in the form in which the `include' appears, without the need for `eval-when'. (*Note Eval When::.) For the same reason, compiling a form that uses `include' results in one compilation unit, composed of multiple files. Loading the compiled file is one `stat' operation for the compilation unit, instead of `2*N' in the case of `load' (once for each loaded source file, and once each corresponding compiled file, in the best case). Unlike `load', `include' also works within nested lexical contexts. It so happens that the optimizer works best within a lexical context, because all of the uses of bindings in a lexical context are visible, so composing files by including them within a `(let () ...)' can sometimes lead to important speed improvements. On the other hand, `include' does have all the disadvantages of early binding: once the code with the `include' is compiled, no change to the included file is reflected in the future behavior of the including form. Also, the particular form of `include', which requires an absolute path, or a path relative to the current directory at compile-time, is not very amenable to compiling the source in one place, but then installing the source to another place. For this reason, Guile provides another form, `include-from-path', which looks for the source file to include within a load path. -- Scheme Syntax: include-from-path file-name Like `include', but instead of expecting `file-name' to be an absolute file name, it is expected to be a relative path to search in the `%load-path'. `include-from-path' is more useful when you want to install all of the source files for a package (as you should!). It makes it possible to evaluate an installed file from source, instead of relying on the `.go' file being up to date. On Sat 24 Dec 2011 00:53, Ian Price writes: > Or am I being ever so slightly patronising? "Recursion and condescension"? :-) http://james-iry.blogspot.com/2009/05/brief-incomplete-and-mostly-wrong.html Cheers, Andy -- http://wingolog.org/