Struct apple_sdk::SdkSearch

pub struct SdkSearch { /* private fields */ }

Search parameters for locating an Apple SDK.

This type can be used to construct a search for an Apple SDK given user chosen search parameters.

The search algorithm is essentially:

1. Iterate through each registered search location.
2. Discover candidate SDKs and filter.
3. Globally sort (if enabled).

Search Locations

Search mechanisms / locations are represented via SdkSearchLocation and internally the searcher maintains a vector of locations. The default search locations are:

1. Use path specified by SDKROOT environment variable, if defined.
2. Find SDKs within the Developer Directory defined by the DEVELOPER_DIR environment variable.
3. Find SDKs within the system installed Xcode application.
4. Find SDKs within the system installed Xcode Command Line Tools.

Simply call Self::location() to register a new location. If the default locations are not desirable, construct an empty instance via Self::empty() and register your explicit list of locations.

An attempt is made to only search a given location at most once. This is done in order to avoid redundant work. If a location is specified multiple times - even via different SdkSearchLocation variants - subsequent searches of that location will yield no distinct results. Duplicate SDKs can occur in the returned list.

Filtering

Filters can be registered to control which SDKs are emitted from the search.

By default, no filtering is performed. This means all SDKs in all search locations are returned. This can return SDKs belonging to multiple platforms (e.g. macOS and iOS).

The following functions control filtering:

• Self::platform()
• Self::minimum_version()
• Self::maximum_version()
• Self::deployment_target()

If you are looking for an SDK to use (e.g. for compilation), you should at least use a platform filter. Otherwise you may see SDKs for platforms you aren’t targeting! It is also an encouraged practice to specify a minimum or maximum SDK version to use.

If you know you are targeting a specific OS version, applying a targeting filter via Self::deployment_target() is recommended. However, this filter is not always reliable. See the caveats in its documentation.

Sorting

By default, the returned list of SDKs is the chained result of SDKs discovered in all registered search locations. The order of the SDK within each search location is likely the sorted order of directory names as they appear on the filesystem.

If using an SDK for compilation, sorting by the SDK version is likely desired. Using the latest/newest SDK that supports a given deployment target is generally a best practice.

Implementations

impl SdkSearch

pub fn empty() -> Self

Obtain an instance with an empty set of search locations.

The search will not resolve any SDKs unless a search location is registered with the instance.

pub fn progress_callback(self, callback: SdkProgressCallback) -> Self

Define a function that will be called to provide updates on SDK search status.

pub fn location(self, location: SdkSearchLocation) -> Self

Add a location to search.

The location will be appended to the current search location list.

pub fn platform(self, platform: Platform) -> Self

Set the SDK platform to search for.

If you do not call this, SDKs for all platforms are returned.

If you are looking for a specific SDK to use, you probably want to call this. If you are searching for all available SDKs, you probably don’t want to call this.

pub fn minimum_version(self, version: impl Into<SdkVersion>) -> Self

Minimum SDK version to require.

Effectively imposes a >= filter on found SDKs.

If using SimpleSdk and the SDK version could not be determined from the filesystem path, the version is assumed to be 0.0 and this filter will likely exclude the SDK.

pub fn maximum_version(self, version: impl Into<SdkVersion>) -> Self

Maximum SDK version to return.

Effectively imposes a <= filter on found SDKs.

pub fn deployment_target(
    self,
    target: impl ToString,
    version: impl Into<SdkVersion>
) -> Self

Deployment target that the SDK must support.

When set, only SDKs that support targeting the given target-version pair will be returned. Example values are (macosx, 10.15).

Only modern SDKs with SDKSettings.json files advertise their targeting settings in a way that allows this filter to work.

Attempting to use this filter on SimpleSdk will result in a run-time error at search time since these SDKs do not parse SDKSettings files.

pub fn sorting(self, sorting: SdkSorting) -> Self

Define the sorting order for returned SDKs.

Default is SdkSorting::None.

pub fn search<SDK: AppleSdk>(&self) -> Result<Vec<SDK>, Error>

Perform a search, yielding found SDKs sorted by the search’s preferences.

May return an empty vector.

pub fn filter_sdk<SDK: AppleSdk>(&self, sdk: &SDK) -> Result<bool, Error>

Whether an SDK matches our search filter.

This is exposed as a convenience method to allow custom implementations of SDK searching using the filtering logic on this type.

Examples found in repository

src/search.rs (line 561)

    pub fn search<SDK: AppleSdk>(&self) -> Result<Vec<SDK>, Error> {
        let mut sdks = vec![];

        // Track searched locations to avoid redundant work.
        let mut searched_platform_dirs = HashSet::new();
        let mut searched_sdks_dirs = HashSet::new();

        for location in &self.locations {
            if let Some(cb) = &self.progress_callback {
                cb(SdkSearchEvent::SearchingLocation(location.clone()));
            }

            // Expand each location to SDKs.
            let resolved = location.resolve_location()?;

            let candidate_sdks = match &resolved {
                SdkSearchResolvedLocation::None => {
                    vec![]
                }
                SdkSearchResolvedLocation::PlatformDirectories(dirs) => dirs
                    .iter()
                    // Apply platform filter.
                    .filter(|dir| {
                        if let Some(wanted_platform) = &self.platform {
                            if &dir.platform == wanted_platform {
                                if let Some(cb) = &self.progress_callback {
                                    cb(SdkSearchEvent::PlatformDirectoryInclude(dir.path.clone()));
                                }

                                true
                            } else {
                                if let Some(cb) = &self.progress_callback {
                                    cb(SdkSearchEvent::PlatformDirectoryExclude(dir.path.clone()));
                                }

                                false
                            }
                        } else {
                            if let Some(cb) = &self.progress_callback {
                                cb(SdkSearchEvent::PlatformDirectoryInclude(dir.path.clone()));
                            }

                            true
                        }
                    })
                    // Apply duplicate search filter.
                    .filter(|dir| {
                        if searched_platform_dirs.contains(dir.path()) {
                            false
                        } else {
                            searched_platform_dirs.insert(dir.path().to_path_buf());
                            true
                        }
                    })
                    .map(|dir| dir.find_sdks::<SDK>())
                    .collect::<Result<Vec<_>, Error>>()?
                    .into_iter()
                    .flatten()
                    .collect::<Vec<_>>(),
                SdkSearchResolvedLocation::SdksDirectory(path) => {
                    if searched_sdks_dirs.contains(path) {
                        vec![]
                    } else {
                        searched_sdks_dirs.insert(path.clone());
                        SDK::find_in_directory(path)?
                    }
                }
                SdkSearchResolvedLocation::SdkDirectory(path)
                | SdkSearchResolvedLocation::SdkDirectoryUnfiltered(path) => {
                    vec![SDK::from_directory(path)?]
                }
            };

            let mut added_count = 0;

            for sdk in candidate_sdks {
                let include = if resolved.apply_sdk_filter() {
                    self.filter_sdk(&sdk)?
                } else {
                    if let Some(cb) = &self.progress_callback {
                        cb(SdkSearchEvent::SdkFilterSkip(sdk.sdk_path()));
                    }

                    true
                };

                if include {
                    sdks.push(sdk);
                    added_count += 1;
                }
            }

            if location.is_terminal() && added_count > 0 {
                break;
            }
        }

        // Sorting should be stable with None variant. But we can avoid the
        // overhead.
        if self.sorting != SdkSorting::None {
            sdks.sort_by(|a, b| self.sorting.compare_version(a.version(), b.version()))
        }

        Ok(sdks)
    }

Trait Implementations

impl Clone for SdkSearch

fn clone(&self) -> SdkSearch

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for SdkSearch

fn default() -> Self

Returns the “default value” for a type.