Learning D - modules packages and the package.d

[Jonathan M Davis]

On Wednesday, April 04, 2018 04:54:50 Ali via Digitalmars-d-learn wrote:
> I am going through the Learning D book by Michael Parker
> So every now and then I will make post about the book
> either critics of the book, book content or questions
>
>
> First critic
> chapter 2 - the special package module
>
> this small section, suggest an idiom to create a package which
> can have any name
> the book suggest somepack
> and inside it add a module package.d , so you will end up
> somepack/package.d
> inside the file add
>
> > module somepack; //notice this named after the folder
> > //then public import std.stdio, somepack.one, somepack.two;
> > //etc
>
> at first i though package.d is special name, as in i must call
> the file package.d or this trick or idiom to work
> also it felt weird that the module name, is named after the
> folder name, which previously was referred to as the package name
>
> anyway, i started playing with this, and renaming everything
> and my conclusion is
>
> i not really sure, if D really support or have packages
> as in D is aware that some modules are together in a package
>
> it seems to me at this time D only support modules
> modules can have names with . in them
> you can use the . in module names to make it seem as if its
> packages
>
> > import io = long.module.name
>
> also seem as a trick that complements having modules with long
> names with dots in them
>
> and it seems you really need to match file and module names
>
> my critic of the chapter 2 so far, the book doesn't really help
> clarify this situation
> i am relieved though to learn that D doesnt treat special
> file/module names as special

In general, modules correspond to files, and packages correspond to folders.
That can be played with by naming modules with names that don't match their
file names, but it tends to cause problems with build tools. In general,
modules and packages should match their corresponding file and folder names
if you don't want problems.

package.d is a special case. package is not a legal module name, so when the
package.d feature was added to the language, the odds of it conflicting with
any existing files were very low. What happens with package.d is that when
you try to import a package rather than a module, the compiled looks for a
package.d file within the package that you're trying to import, and it
imports that module. The typical thing to do is to have the module name
within that module match the package name. I don't know what happens if you
try to do otherwise, but I wouldn't expect it to work, because in this case,
the compiler is specifically looking for package.d and not the module with
with matching module declaration. _That_ is all that's special about
package.d - it's what's imported you try to import a package.

Now, if there is a package.d, it's typically the case that it has public
import statements for the modules inside the package so that importing the
package will then import all of the modules within the package, but what
actually gets imported when importing the package is entirely dependent on
what's in package.d. It can define symbols of its own, and it doesn't _have_
to publicly import anything. And since public imports can be used in any
module, there's nothing really special about them in package.d. It's just
that using them in package.d makes it possible to have it be the case that
importing a package imports all of the modules within that package.

The entire reason that the package.d feature was added to the language was
so that a module could be broken up into multiple modules within a package
with the same name without breaking code in the process - e.g.
std.algorithm, std.container, std.datetime, and std.range were all
originally modules, but now, they're all packages. Personally, I don't think
that it's great practice to use package.d if you don't have to (and
importing that many symbols at once can negatively impact compilation
times), but some folks like to use it for their libraries so that you can
import everything at once.

- Jonathan M Davis