New crate layout is confusing for previous users

[workingjubilee]

There probably should be a slightly more thorough migration guide to the new crate design, or more and more "modernized" examples of its use, especially in terms of features.

[pheki]

Hey! When I have more time I'll go back to this and improve the docs. For now I'll explain my plan and include a sketch migration guide (with rationale) in case it's of interest. See also: CHANGELOG.md

The plan

• Add the following line to the start of the READMEs:

If you're interested in Vita development in Rust, please check out the organization-wide docs and the Rust on Sony PlayStation Vita Book. There are also working examples at examples.

• Point to vitasdk and henkaku wiki docs, maybe C vitasdk's samples. Edit: we already have lot's of links to vitasdk on the org and on the book, which has links to the wiki and C examples. I'm not sure where to add these without bloating docs with too many links.
• Add a # Features section on the README that explains (with an example) how features work, including how to search if a native function needs a feature
• Update the vitasdk-sys example, move it into the examples repo, create an integration test to compensate for it (suggested by @nikarh in the past). Done in Added vitasdk example examples#4 and Add tests and remove example #26
• Polish the migration guide below and add it somewhere in the repo then link to it in the README. Added info on the README pointing to this comment.

v0.3 Migration Guide

Breaking changes

There are basically 2 breaking changes:

1. All items have moved to the crate root, so you need to import from the root instead:

Before:

use vitasdk_sys::{
    psp2::{
        display::sceDisplaySetFrameBuf,
        kernel::sysmem::{
            sceKernelAllocMemBlock, sceKernelFreeMemBlock, sceKernelGetMemBlockBase,
        },
    }, 
    psp2common::{
        display::{SceDisplayFrameBuf, SceDisplaySetBufSync::SCE_DISPLAY_SETBUF_NEXTFRAME},
        kernel::sysmem::SCE_KERNEL_MEMBLOCK_TYPE_USER_CDRAM_RW,
        types::SceUID,
    },
};

After:

use vitasdk_sys::{
    sceDisplaySetFrameBuf, sceKernelAllocMemBlock, sceKernelFreeMemBlock, sceKernelGetMemBlockBase,
    SceDisplayFrameBuf, SceUID, SCE_DISPLAY_SETBUF_NEXTFRAME,
    SCE_KERNEL_MEMBLOCK_TYPE_USER_CDRAM_RW,
};

2. We used to automatically link to all stubs available and had no features. Now we have one feature per stub, with items gated on the feature. The job here is to basically go over every item (that fails to compile) on docs.rs/vitasdk-sys and check which feature is required.

Using the example above, by searching the docs for sceDisplaySetFrameBuf we find: Available on crate feature SceDisplay_stub only. Meaning you have to enable SceDisplay_stub for vitasdk-sys.

Considering all imports on the example above (1.), Cargo.toml would have:

[dependencies.vitasdk-sys]
version = "0.3.2"
features = [
    "SceSysmem_stub",
    "SceDisplay_stub",
]

Rationale

1. Upstream (vita-headers) moves files all the time, which means breaking changes because of the tree structure. Using a flat structure is easier to use and also means there should be no more namespace changes.

2. On 0.1 and 0.2 I had setup build.rs to always link to all vitasdk stubs (more than 200), except for a few with conflicting symbols. It was done that way mostly because I just wanted to get something out and I didn't know db.yml files existed (which allow us to "easily" trace which symbols depend on which stubs). @zetanumbers basically rewrote binding generation from scratch so you can now choose which stubs get included.