Jump to page: 1 2
Thread overview
Season of Docs
Mar 15, 2019
Seb
Mar 15, 2019
Dennis
Mar 16, 2019
JN
Mar 18, 2019
Guillaume Piolat
Mar 18, 2019
Guillaume Piolat
Mar 18, 2019
kevin brack
Mar 19, 2019
Walter Bright
Mar 19, 2019
Mike Franklin
Mar 19, 2019
Walter Bright
Mar 19, 2019
Mike Franklin
Mar 19, 2019
Walter Bright
Mar 19, 2019
Mike Franklin
Mar 19, 2019
Walter Bright
Mar 19, 2019
Nicholas Wilson
Mar 19, 2019
Paolo Invernizzi
Mar 19, 2019
Walter Bright
Mar 19, 2019
Paolo Invernizzi
Mar 19, 2019
Nicholas Wilson
Mar 19, 2019
Paolo Invernizzi
Mar 19, 2019
Olivier FAURE
March 15, 2019
Google recently announced the Season of Docs:

https://developers.google.com/season-of-docs

Would anyone be interested in participating as a writer or mentor?

Where do you think D has the deepest need of good technical documentation?
March 15, 2019
On Friday, 15 March 2019 at 16:52:12 UTC, Seb wrote:
> Where do you think D has the deepest need of good technical documentation?

When it comes to technical documentation, the dmd codebase could really use some comments. Take these files for example:
https://dlang.org/phobos/dmd_s2ir.html
https://dlang.org/phobos/dmd_todt.html
https://dlang.org/phobos/dmd_eh.html
Eh? Those acronyms aren't immediately obvious, and there isn't a header that explains what the module is about.

Not to mention the back-end, where you have such descriptive filenames as 'cod1.d' to 'cod5.d', and documentation completely missing:
https://dlang.org/phobos/dmd_backend_cod1.html
"Oh No! Page Not Found"

This is more helpful already:
https://wiki.dlang.org/DMD_Source_Guide

But it is full of statements like:
"Note: This section may be considerably outdated. Please bring it up to date where you can."

An this gem:
"Symbol - Appears to have something to do with the names used by the linker."
This is what I expect to hear from a reverse engineering project, not an open source codebase.

---

Secondly, the command line reference of dmd is pretty bare too

https://dlang.org/dmd-windows.html

-shared
    Generate DLL library

If I interpreted https://wiki.dlang.org/Win32_DLLs_in_D correctly, it doesn't actually generate a DLL, it just disables an optimization that's not valid in DLL's. You still have to put the resulting .obj through a linker manually or add -of=mylibrary.dll.

---

Finally, Dub.

Possibly technical documentation isn't the solution here, but I still wanted to mention how often I go back to the json/sdl package reference trying to get Something Simple done. Build options, -settings, -requirements, -types and -configurations are mentioned. It still confuses me.
More of https://github.com/dlang/dub/wiki/Cookbook would be nice.

https://dub.pm/advanced_usage.html
"Execute dub <command> -h for more information on these commands."

Please just include all info in the docs thank you very much.
March 16, 2019
On Friday, 15 March 2019 at 21:07:45 UTC, Dennis wrote:
> If I interpreted https://wiki.dlang.org/Win32_DLLs_in_D correctly, it doesn't actually generate a DLL, it just disables an optimization that's not valid in DLL's. You still have to put the resulting .obj through a linker manually or add -of=mylibrary.dll.
>
> ---
>
> Finally, Dub.
>

Also, both. I'd like to know how to create DLLs when building with dub.
March 18, 2019
On Friday, 15 March 2019 at 21:07:45 UTC, Dennis wrote:
> On Friday, 15 March 2019 at 16:52:12 UTC, Seb wrote:
>> [...]
>
> When it comes to technical documentation, the dmd codebase could really use some comments. Take these files for example:
> https://dlang.org/phobos/dmd_s2ir.html
> https://dlang.org/phobos/dmd_todt.html
> https://dlang.org/phobos/dmd_eh.html
> Eh? Those acronyms aren't immediately obvious, and there isn't a header that explains what the module is about.
>
> [...]

Great thanks for this help
March 18, 2019
On Saturday, 16 March 2019 at 14:30:59 UTC, JN wrote:
>
> Also, both. I'd like to know how to create DLLs when building with dub.

It's really not that complicated!


# BUILD

In your dub.json, use the targetType

    "targetType": "dynamicLibrary",

Mixin that template for creating a DLL:

-------------- dllmain.d --------------

// Dynamic libraries entry point.
// Basically only needed on Windows, on POSIX the other entry points are sufficient.

version(Windows)
{
    template DLLEntryPoint()
    {
        const char[] DLLEntryPoint = q{
            import core.sys.windows.windef;
            import core.sys.windows.dll;
            extern (Windows) BOOL DllMain(HINSTANCE hInstance, ULONG ulReason, LPVOID pvReserved)
            {
                return true;
            }
        };
    }
}
else
{
    template DLLEntryPoint()
    {
        const char[] DLLEntryPoint = ``;
    }
}


---------------------------------------


IMPORTANT: Use `export` for any call you want exported in your DLL!






(Optional: Use some OS-specific tricks to get a static runtime instead of an annoying, shared one, for example:

    // Windows: There is now a new LDC flag to do this, use it instead
    "lflags-windows-ldc": [
        "libcmt.lib",
        "/nodefaultlib:msvcrt.lib",
        "/nodefaultlib:vcruntime.lib"
    ],

    // Linux
    "dflags-linux-dmd": ["-defaultlib=libphobos2.a"],

    // OSX, not sure for DMD
    "dflags-osx-ldc": ["-static"],

)



# CODE

## I DON'T WANT TO USE THE RUNTIME

Either use -betterC, or (a bit easier) link with the runtime but never enable it. Mark your entry points "nothrow @nogc", use no TLS, no global dtor/ctor, and try to live within the @nogc world.


## I WANT TO USE THE RUNTIME

Use LDC special ctor/dtor to call Runtime.initialize() and Runtime.finalize()

https://wiki.dlang.org/LDC-specific_language_changes#LDC_global_crt_ctor_and_LDC_global_crt_dtor

If you don't use them, you will need some sort of initialization entry points, or a shady lazy mechanism.

AND THEN on every entry points, attach incoming threads with `thread_attachThis()` and detach them with `thread_detachThis()`. Don't keep threads attached when they have quite your dynlib and might be killed by a host program, you will suffer quite a bit if you do.


Hope it helps! It has been doable for YEARS to make dynlib with D.


March 18, 2019
On Monday, 18 March 2019 at 21:28:05 UTC, Guillaume Piolat wrote:
> Hope it helps! It has been doable for YEARS to make dynlib with D.


Also: you don't need a .def anymore since `export` works in both LDC and DMD for Windows. It is unneeded since about 3 years.
March 19, 2019
On Friday, 15 March 2019 at 16:52:12 UTC, Seb wrote:

> Where do you think D has the deepest need of good technical documentation?

The `return` and `scope` attribute (e.g. DIP25 and DIP1000) need a lot of help.  In addition to the semantics themselves, there are other behaviors that need documentation:

1) Attributes are often inferred, but how and when this inference occurs is not documented.  I remember playing around to try and figure it out, and I found that the even when explicitly marking something with `scope`, the compiler removed it due to the inference rules.  That was alarming to me.

2) Walter introduced a convention where the first parameter of a function is treated differently than others.  This behavior needs to be documented (and should be reverted, IMO). See https://github.com/dlang/dmd/pull/8504

It is critical that the developer that introduces a feature document it sufficiently.  After the documentation is primed with the initial explanation, the rest of the community can inherit it and build on it.  But without that initial documentation, noone else knows what to write.  See https://forum.dlang.org/post/jmdlnsijowsdmiuhfrwn@forum.dlang.org

Mike


March 18, 2019
Sounds like a post you should put up on bugzilla.
March 18, 2019
On 3/18/2019 6:59 PM, Mike Franklin wrote:
> I found that the even when explicitly marking something with `scope`, the compiler removed it due to the inference rules.  That was alarming to me.

I don't know of a case where it does that. It would be a bug.
March 19, 2019
On Tuesday, 19 March 2019 at 05:10:57 UTC, Walter Bright wrote:
> On 3/18/2019 6:59 PM, Mike Franklin wrote:
>> I found that the even when explicitly marking something with `scope`, the compiler removed it due to the inference rules.  That was alarming to me.
>
> I don't know of a case where it does that. It would be a bug.

I sent you an e-mail about it on June 28, 2018.  Here's the code in the compiler that I alluded to.

https://github.com/dlang/dmd/blob/25b1f0a55159d2addfc2edd5ff1de3c8c983f66e/src/dmd/typesem.d#L1358-L1363

```D
if (fparam.storageClass & STC.scope_ && !fparam.type.hasPointers() && fparam.type.ty != Ttuple)
{
    fparam.storageClass &= ~STC.scope_;
    if (!(fparam.storageClass & STC.ref_))
        fparam.storageClass &= ~STC.return_;
}
```

The following code fails as a result:
```D
void foo(scope int p);

static assert(__traits(getParameterStorageClasses, foo, 0)[0] == "scope");
```

Revisiting this just now, I realize that if I make the parameter `scope int* p` instead of `scope int p` it works fine.  Maybe that is by design (yuck!), maybe it's not, I don't know because it's not sufficiently documented.

Regardless, the compiler shouldn't be removing anything the user explicitly specifies.  Instead, it should give the user an error.

I can't submit bug reports against a non-existent specification.  Without the spec, how am I supposed to know whether or not its a bug, and how is a developer supposed to know what to do for the fix?  It's a no-win situation.

Also, some of your DIP 1000 PRs should not have been merged because they lacked enough documentation for anyone to do a proper review, but my concerns fell on deaf ears.  And just any documentation is not sufficient.  To this day, you're still fielding questions on the forum because noone knows how it's supposed to work; they're just speculating.  Perhaps if you documented it, others might know how to leverage it and help you with your immediate goal of improving Phobos.

Mike



« First   ‹ Prev
1 2