valac --vapi --internal-vapi --fast-vapi

Question

// Point.vala
namespace Test {
    class Point {
        public const int MY_CONST = 123;
        public float x { get; set; }
        public float y { get; set; }
    }
}

There is a vala source file, 'Point.vala'

1. --vapi

valac --vapi=Point.vapi --library=point -X -shared Point.vala:

// Point.vapi
namespace Test {
}

empty...

2. --internal-vapi

valac --internal-vapi=Point.vapi --header=Point.h --internal-header=Point_internal.h --library=point -X -shared Point.vala:

// Point.vapi
namespace Test {
    [CCode (cheader_filename = "Point_internal.h")]
    internal class Point {
        public const int MY_CONST;
        public Point ();
        public float x { get; set; }
        public float y { get; set; }
    }
}

it seems perfect and works for me

3. --fast-vapi

valac --fast-vapi=Point.vapi --library=point -X -shared Point.vala:

// Point.vapi
using GLib;
namespace Test {
    internal class Point {
        public const int MY_CONST = 123; // error
        public Point ();
        public float x { get; set; }
        public float y { get; set; }
    }
}

this raises an error, error: External constants cannot use values, when using this vapi

Q1: What is exact difference? and why are there the options.

Q2: For creating shared lib, Should I use --internal-vapi?

Answer 1

Your class doesn't specify its visibility, so it has "internal" visibilty by default.

That means it's only visible to other classes inside your namespace.

If you specify the class as public the --vapi switch will output a vapi files as expected:

// Point.vala
namespace Test {
    // Make it public!
    public class Point {
        public const int MY_CONST = 123;
        public float x { get; set; }
        public float y { get; set; }
    }
}

Invocation:

valac --vapi=Point.vapi --library=point -X -shared Point.vala

Result:

/* Point.vapi generated by valac.exe 0.34.0-dirty, do not modify. */

namespace Test {
        [CCode (cheader_filename = "Point.h")]
        public class Point {
                public const int MY_CONST;
                public Point ();
                public float x { get; set; }
                public float y { get; set; }
        }
}

So --vapi will output public types only and --internal-vapi will in addition output internal types as well.

I don't know what --fast-vapi is for.

As to your second question, you should normally use public classes for shared libraries. The whole point of the internal vs public visibility is that public types are meant for consumption by the public (outside the namespace) while internal types are meant for internal implementation details only.