can't find swift darwin documentation

Question

I'm playing around with swift and have the following simple code

I want to check how "sqrt" function is implemented, so I tried to click on "Darwin.C.math" link but nothing happened. I googled "Swift darwin apple documentation" but nothing about "Darwin" came up. So could someone please tell me, how I can find the documentation on the "sqrt" function?

In java, when I click on a class name or a method name, the source code file will appear, which include all the details on how the method and class is implemented. But I can't seem to do the same with swift/xcode.

Answer 1

The documentation for sqrt is available by running man sqrt. Most Darwin functions are C functions bridged to Swift, and they're not documented inside of Xcode.

But you're asking for the implementation, which is a completely different thing than the documentation. To provide you with the implementation, you'd have to have all the source code, and things like stdlib, Foundation, and Darwin don't provide that directly because they're pre-compiled. Some of them are open source so you can in principle find the source code, but it's still very difficult to know that this is precisely the code you're using. This is pretty typical of compiled languages since there's no easy way to decompile them.

That said, most of the source code, as Ben notes, is available in various places if you know where to look. sqrt(Double) is a good example of when this fails, though, because there is no implementation in the way you're likely thinking. It's inlined directly by the compiler via __builtin_sqrt. On an Intel processor, that may be directly converted to the fsqrt operation, it may be vectorized, it might be evaluated at compile time, or it might be inlined in various other ways. On different platforms, there are different options.

In your example, it's computed at compile time and encoded as though you'd written var result = 3.0. You can see this in the LLVM IR output:

echo "import Darwin; var result = sqrt(9.0)" | swiftc -emit-ir -O -

...
define i32 @main(i32, i8** nocapture readnone) local_unnamed_addr #0 {
entry:
  store double 3.000000e+00, double* getelementptr inbounds (%TSd, %TSd* @"$S4main6resultSdvp", i64 0, i32 0), align 8
  ret i32 0
}
...

So there isn't any "implementation" that you could pull up. There is no real sqrt function (though at least some versions of macOS have a fake one).

That said, I agree that it's really annoying that the relevant man pages aren't imported into Xcode somehow. It's probably a lot of work to do that because the docs for those functions are written in troff, which is probably a pain to convert to the doc format Xcode uses, but even so it'd be nice.

Answer 2

Darwin is a part of Apple's Open Source Projects. There you can view all open-source software in macOS (like 11.2) and iOS (like 13.5.1), as well as documentation about Darwin and Apple's approach to implementing Unix via BSD.

Additionally, most Darwin APIs are implementations of the UNIX specification (with some notable differences), so simply look up any one of many UNIX documentation sites, like these:

• Apple Manual Pages (sqrt)
• IEEE Std 1003.1-2017 (sqrt)
• UNIX.org (uses the above link for API documentation)
• FreeBSD Documentation (sqrt)
• The C Library Reference Guide from The Washington State University / University of Illinois
• ANSI C Standard Library Documentation (sqrt)

etc 🙂

You can also use man pages on your computer from the CLI. For example, in your use case, just open a Terminal and type man sqrt:

SQRT(3)                  BSD Library Functions Manual                  SQRT(3)

NAME
     sqrt -- square root function

SYNOPSIS
     #include <math.h>

     double
     sqrt(double x);

     long double
     sqrtl(long double x);

     float
     sqrtf(float x);

DESCRIPTION
     The sqrt() function compute the non-negative square root of x.

SPECIAL VALUES
     sqrt(-0) returns -0.

     sqrt(x) returns a NaN and generates a domain error for x < 0.

VECTOR OPERATIONS
     If you need to apply the sqrt() function to SIMD vectors or arrays, using the following functions provided by the Accelerate.frame-
     work may give significantly better performance:

     #include <Accelerate/Accelerate.h>

     vFloat vsqrtf(vFloat x);
     vFloat vrsqrtf(vFloat x);
     void vvsqrtf(float *y, const float *x, const int *n);
     void vvsqrt(double *y, const double *x, const int *n);
     void vvrsqrtf(float *y, const float *x, const int *n);
     void vvrsqrt(double *y, const double *x, const int *n);

SEE ALSO
     math(3)

STANDARDS
     The sqrt() function conforms to ISO/IEC 9899:2011.

BSD                            December 11, 2006                           BSD

You can also use online manual pages in case that's more your style: https://www.freebsd.org/cgi/man.cgi