Main Content

このページの翻訳は最新ではありません。ここをクリックして、英語の最新版を参照してください。

継続的インテグレーション システム ワークフローにおけるメトリクスのしきい値違反の修正

この例では、メトリクス ダッシュボードをオープンソース ツールである GitLab™ および Jenkins™ と連携させ、継続的インテグレーション システム ワークフローでモデルのテストおよび調整を行う方法を説明します。継続的インテグレーションとは、開発者が作業中のすべてのプロジェクト ファイルのコピーを共有メインラインにマージさせる手法です。このワークフローによって時間が節約され、バージョン コントロールの維持、およびテストの自動化および標準化を通して品質が向上されます。

この例では、付属のプロジェクトmatlab:sldemo_slproject_airframe、および提供しなければならない以下のファイルを含むプロジェクトを参照します。

  • メトリクスのしきい値を指定し、メトリクス ダッシュボードをカスタマイズする MATLAB スクリプト。

  • メトリクス データを収集し、メトリクスのしきい値違反がないかをチェックする MATLAB ユニット テスト。

この例では、MATLAB ユニット テストを実行してメトリクスのしきい値違反があるかを判別するために、Jenkins の継続的インテグレーション サーバーを使用します。Jenkins ではテスト結果がアーカイブされ、これをダウンロードしてローカルで調査できます。GitLab はオンラインの Git リポジトリ マネージャーで、Jenkins と連携するよう設定できます。次の図は、Simulink Check、GitLab、および Jenkins が継続的インテグレーション ワークフローにおいてどのように連携するかを示します。

プロジェクトの設定

matlab:sldemo_slproject_airframeプロジェクトのファイルに加えて、以下の追加ファイルを提供しなければなりません。

  • プロジェクトのメトリクス データを収集し、モデル ファイルにメトリクスのしきい値違反が含まれていないことをチェックする MATLAB ユニット テスト。MATLAB ユニット テストの詳細については、スクリプト ベースのユニット テストを参照してください。

  • メトリクスのしきい値を指定し、メトリクス ダッシュボードをカスタマイズする MATLAB スクリプト。メトリクス ダッシュボードのカスタマイズ方法の詳細については、メトリクス ダッシュボードのレイアウトおよび機能のカスタマイズを参照してください。

  • メトリクスのしきい値の定義、カスタム メトリクス ファミリの設定、メトリクス ダッシュボードのレイアウトのカスタマイズを行うコンフィギュレーション XML ファイルをアクティブにする setup.m ファイル。この例では、setup.m スクリプトには以下のコードが含まれています。

    function setup
        % refresh Model Advisor customizations
        Advisor.Manager.refresh_customizations();
            
        % set metric configuration with thresholds
        configFile = fullfile(pwd, 'config', 'MyConfiguration.xml');
        slmetric.config.setActiveConfiguration(configFile);
        
        uiconf = fullfile(pwd, 'config', 'MyDashboardConfiguration.xml');
        slmetric.dashboard.setActiveConfiguration(uiconf);
    end
    
    [プロジェクト] タブで、[起動とシャットダウン] をクリックします。[起動ファイル] フィールドで、setup.m ファイルを指定します。

  • モデル アドバイザー チェックをカスタマイズするためにモデル アドバイザー構成ファイルをアクティブにする sl_customization.m ファイル。独自のモデル アドバイザー設定の作成方法の詳細については、準拠メトリクスの設定を参照してください。

  • Jenkins ビルド時に実行される run スクリプト。この例では、次のコードが run.m ファイルに記述されています。

    % script executed during Jenkins build
    function run(IN_CI)
         if (IN_CI)
            jenkins_workspace = getenv('WORKSPACE');
            cd(jenkins_workspace);
        end
    
        % open the sl project
        slproj = simulinkproject(pwd);
        
        % execute tests
        runUnitTest();
        
        slproj.close();
        
        if IN_CI
            exit
        end
    end
    

  • アクティブなメトリクス構成を既定の構成にリセットする cleanup.m ファイル。この例では、次のコードが cleanup.m ファイル スクリプトに記述されています。

    function cleanup    
        rmpath(fullfile(pwd, 'data'));
        Advisor.Manager.refresh_customizations();
    
        % reset active metric configuration to default
        slmetric.config.setActiveConfiguration('');
        slmetric.dashboard.setActiveConfiguration('');
    end
    
    [プロジェクト] タブで、[起動とシャットダウン] をクリックします。[シャットダウン ファイル] フィールドで、cleanup.m ファイルを指定します。

  • 派生したアーティファクトが GitLab にチェックインされていないことを検証する .gitignore ファイル。次のコードが .gitignore ファイルに記述されています。

    work/**
    reports/**
    *.asv
    *.autosave
    

GitLab の設定

プロジェクトのソース管理のための GitLab プロジェクトを作成します。詳細については、https://docs.gitlab.com/ee/README.htmlを参照してください。

  1. Git クライアントをインストールします。

  2. 分岐ワークローを設定します。GitLab で、メイン ブランチから、モデル ファイルに変更を実装するための一時的なブランチを作成します。統合担当のエンジニアは Jenkins のテスト結果を使用して、一時的なブランチをマスター ブランチにマージすべきかを判断できます。詳細については、以下を参照してください。

    https://git-scm.com/book/en/v1/Git-Branching-Branching-Workflows

  3. [Settings][Repository] で、開発者がマスター ブランチに変更をマージする際にマージ要求の使用を強制することで、マスター ブランチを保護します。

  4. [Integrations] ページの [Settings] で、Jenkins プロジェクトの URL に Web フックを追加します。この Web フックは、Jenkins サーバー上のビルド ジョブをトリガーします。

Jenkins の設定

GitLab および TAP プラグインをインストールします。MATLAB ユニット テストは TAPPlugin を使用して結果を .tap ファイルにストリーミングします。Jenkins は .tap ファイルをインポートすることで、MATLAB から Jenkins ジョブへのテスト状態の通信を可能にします。

Jenkins プロジェクトを作成します。次の設定を指定します。

  1. Jenkins プロジェクトで [Configure] をクリックします。

  2. [General] タブで、プロジェクト名を指定します。

  3. [Source Code Management] タブの [Repository URL] フィールドで、GitLab リポジトリの URL を指定します。

  4. [Build Triggers] タブで、[Build when a change is pushed to GitLab] を選択します。

  5. [Build] タブで MATLAB を実行し、実行スクリプトを呼び出します。実行スクリプトによりプロジェクトが開き、すべてのユニット テストが実行されます。この例のプロジェクトでは、コードは次のとおりです。

    matlab -nodisplay -r...
     "cd /var/lib/jenkins/workspace/'18b Metrics CI Demo'; run(true)"

  6. [Post-build Actions] タブで、TAP 形式の結果が Jenkins にパブリッシュされるよう TAP プラグインを設定します。[Test Results] フィールドで reports/*.tap を指定します。[Files to archive]reports/**,work/** を指定します。

    TAP プラグインは、ジョブの結果を拡張して MATLAB ユニット テストからの詳細を表示します。Jenkins のアーカイブ インフラストラクチャによって、Jenkins のビルド時に生成された派生アーティファクトが保存されます。

継続的インテグレーション ワークフロー

プロジェクト、Jenkins、および GitLab の設定後、継続的インテグレーション ワークフローに従います。

段階 1: 機能の開発

  1. GitLab リポジトリのクローンをローカルに作成します。Git リポジトリからのファイルの取得を参照してください。

  2. Simulink で、ローカルの GitLab リポジトリに移動します。

  3. 機能ブランチを作成し、ファイルを取得し、チェックアウトします。Git でのブランチとファイルのマージGit でのファイルのプル、プッシュおよび取得を参照してください。

  4. プロジェクト ファイルに必要な変更を加えます。

  5. モデルをシミュレートし、シミュレーション データ インスペクターで出力を検証します。

  6. MATLAB ユニット テストを実行します。詳細については、runtestsを参照してください。

  7. 変更したモデルを機能ブランチに追加およびコミットします。Git でのブランチとファイルのマージGit でのファイルのプル、プッシュおよび取得を参照してください。

  8. GitLab リポジトリに変更をプッシュします。Git でのブランチとファイルのマージGit でのファイルのプル、プッシュおよび取得を参照してください。

  9. GitLab で、マージ要求を作成します。ソース ブランチとして機能ブランチを、マスター ブランチとしてターゲット ブランチを選択します。[Compare Branches and Continue] をクリックします。

  10. 機能が完全に実装されていない場合、要求の先頭に WIP: という文字を追加して、マージ要求を作成中としてマークします。マージ要求が WIP: とマークされていない場合、作成後のビルドが直ちにトリガーされます。

  11. [Submit Merge Request] をクリックします。

段階 2: 継続的インテグレーションを使用した検定

  1. WIP: という文字がマージ要求の先頭にない場合、プッシュ コマンドによって Jenkins ビルドがトリガーされます。この例の Jenkins の設定の部分で、GitLab に変更をプッシュしたときにビルドを実行するよう Jenkins の設定を行いました。文字を削除するには、[Resolve WIP status] をクリックします。

  2. Jenkins プロジェクトに移動します。[Build History] でビルド ステータスを参照できます。

  3. ビルドをクリックします。

  4. [Tap Test Results] をクリックします。

  5. この例では、MetricThresholdGateway.m ユニット テストは、3 つのメトリクスのしきい値を満たさなかったためにパスしませんでした。このデータを調査するには、データをローカルにダウンロードしなければなりません。

段階 3: 品質問題をローカルで調査

  1. アーカイブされた結果をローカルの Git リポジトリのワークスペースにダウンロードします。

  2. ダウンロードしたファイルを解凍します。reports/ および work/ フォルダーをローカル リポジトリ内のそれぞれのフォルダーにコピーします。

  3. プロジェクトおよびメトリクス ダッシュボードを開き、結果を確認します。

  4. モデルに対して必要な更新を行い、テスト エラーを解決します。GitLab の機能ブランチに変更をプッシュします。

  5. 統合担当のエンジニアは Jenkins のテスト結果を使用して、一時的なブランチをマスター ブランチにマージするのに適切なタイミングを判断できます。

参考

|

関連するトピック