规范目录

规范目录是一套为开发Objective-C和Swift "组件"集合而设计的运行时工具和约定。

概述

如果你的团队同时在许多组件上工作，你可能发现构建示例和单元测试涉及一些非平凡的冗余

• 每个组件的Xcode项目的维护。
• 每个组件的示例和测试目标的维护。
• 在项目/目标/工作空间之间切换。

解决这个问题的一个方法是为所谓的"目录"应用程序创建"目录"。目录的目的是在一个应用程序中展示组件集合的使用。目录应用程序减少了您的团队需要与之交互的不同Xcode目标数量。您的团队管理目录的Xcode项目，根据需要添加和更新文件。

如果——不是管理Xcode项目——你只需创建新的源文件并运行pod install会怎么样呢？

规范目录通过结合约定和CocoaPods来最小化创建示例和单元测试的工程负担。只需运行 pod install，您的目录将包括所有示例和单元测试，这两个都是易于访问的目标。

剩下的唯一的工程负担就是实际编写示例和测试。

示例

示例目录位于example/目录下。运行pod install来设置它

pod install --project-directory=example/
open example/Catalog.xcworkspace

打开项目后，您会找到两个目标：Catalog和UnitTests。运行Catalog。

您可以在目录应用程序中导航到单个组件的示例。

现在尝试运行单元测试。您将在单元测试输出中看到出现一个电阻测试。

添加新示例的快速介绍

打开以下目录

open example/components/Resistor/examples/

1. 复制任何一个示例。
2. 在复制中给类一个唯一的名字。
3. 将+catalogBreadcrumbs路径改为独一无二的名称。
4. 运行pod install --project-directory=example/并重新构建应用程序。
5. 您的示例现在将列在电阻下。

这五个步骤描述了将新示例添加到目录的完整过程。

添加新测试的快速介绍

打开以下目录

open example/components/Resistor/tests/unit/

1. 复制任何一个测试。
2. 在复制中给类一个唯一的名字。
3. 运行pod install --project-directory=example/并重新构建应用程序。
4. 运行单元测试。

设置指南

此指南将指导您如何创建一个使用CatalogByConvention库的Catalog项目。

步骤 1：规划组件约定

这是最重要的步骤。这里最重要的是，您需要在每个组件中一致地应用约定。

让我们看看example/目录中包含的示例遵循的约定

components/
  ComponentNameCamelCased/
    examples/
      SomeExample.m
    src/
      Resistor.h
      RESClass.h
      RESClass.m
    tests/
      unit/
        SomeUnitTest.m

步骤 2：创建必要的文件/文件夹

除了components/目录外，我们还将创建以下内容

• 一个catalog/目录。
• 一个CatalogExamples.podspec文件。
• 一个CatalogUnitTests.podspec文件。
• 一个Podfile文件。

最终的结果将看起来像这样

catalog/
components/
CatalogExamples.podspec
CatalogUnitTests.podspec
Podfile

步骤 3：创建标准 podspec

让我们看一下 CatalogExamples.podspec 和 CatalogUnitTests.podspec 的内容。

在 CatalogExamples.podspec 内部

Pod::Spec.new do |s|
  s.name         = "CatalogExamples"
  s.version      = "1.0.0"
  s.summary      = "Convention for catalog examples."
  s.homepage     = "https://github.com/your/repo"
  s.authors      = "Catalog"
  s.license      = 'Apache 2.0'
  s.source       = { :git => "https://github.com/your/repo.git", :tag => s.version.to_s }
  s.requires_arc = true
  
  # Conventions
  s.source_files = 'components/*/examples/*.{h,m,swift}'
  s.public_header_files = 'components/*/examples/*.h'
  s.resources = ['components/*/examples/resources/*']
end

在 CatalogUnitTests.podspec 内部

Pod::Spec.new do |s|
  s.name         = "CatalogUnitTests"
  s.version      = "1.0.0"
  s.summary      = "Convention for catalog tests."
  s.homepage     = "https://github.com/your/repo"
  s.authors      = "Catalog"
  s.license      = 'Apache 2.0'
  s.source       = { :git => "https://github.com/your/repo.git", :tag => s.version.to_s }
  s.requires_arc = true
  s.framework = 'XCTest'
  
  # Conventions
  s.source_files = 'components/*/tests/unit/*.{h,m,swift}'
  s.resources = ['components/*/tests/unit/resources/*']
  
  # Unit tests require you to specify your components as dependencies.
  s.dependency 'Resistor'
end

步骤 4：为您的目录创建一个 Podfile

现在让我们编辑 Podfile。

您可以使用以下模板作为起点，并根据需要更新目标、路径和依赖项的名称。

abstract_target 'Catalog' do
  workspace 'Catalog.xcworkspace'
  use_frameworks! 
  
  pod 'CatalogByConvention'
  
  # Define where the local pods live. This allows your conventions to depend on them.
  pod 'Resistor', :path => 'components/Resistor'
  
  target "Catalog" do
    project 'catalog/Catalog.xcodeproj'
    pod 'CatalogExamples', :path => './'
  end
  
  target "UnitTests" do
    project 'catalog/Catalog.xcodeproj'
    pod 'CatalogUnitTests', :path => './'
  end
end

步骤 5：创建 Catalog Xcode 项目

创建一个新的 Xcode 项目。我们假设您正在使用“单个视图应用程序”模板。为项目启用单元测试。

确保您的应用程序和单元测试目标与在您的 Podfile 中定义的相匹配。

删除默认的 ViewController 类。

更新您的应用程序代理以类似于以下内容

import UIKit
import CatalogByConvention

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  
  var window: UIWindow?
  
  func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    self.window = UIWindow(frame: UIScreen.mainScreen().bounds)
    
    let rootViewController = CBCNodeListViewController(node: CBCCreateNavigationTree())
    rootViewController.title = "Catalog by Convention"
    
    let navController = UINavigationController(rootViewController: rootViewController)
    self.window?.rootViewController = navController
    
    self.window!.makeKeyAndVisible()
    return true
  }
}

步骤 6：运行 pod install

为您的 Catalog 运行 pod install。打开您 Catalog 的工作区。

pod install
open Catalog.xcworkspace

您所有示例、单元测试和组件源代码都将位于工作区中的 Pods 项目中。

步骤 7：构建！

从现在开始，您只需创建新的示例和单元测试源代码文件，它们将在后续的 pod install 过程中自动获得。

持续步骤：添加示例

要让示例视图控制器出现在您的项目中，您的视图控制器必须实现 +catalogBreadcrumbs。例如

@implementation ParallelResistorExample (CatalogByConvention)

+ (NSArray<NSString *> *)catalogBreadcrumbs {
  return @[ @"Resistor", @"Parallel" ];
}

@end

许可信息

遵循 Apache 2.0 许可证。详情请见 LICENSE 文件。