KiCad PCB EDA Suite
Loading...
Searching...
No Matches
command_project_downgrade.cpp
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
5 *
6 * This program is free software: you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation, either version 3 of the License, or (at your
9 * option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <https://www.gnu.org/licenses/>.
18 */
19
21#include "cli/exit_codes.h"
23
24#include <json_common.h>
25#include <filesystem>
26#include <kiplatform/io.h>
27#include <downgrade_copy.h>
28#include <downgrade_scan.h>
29
30#include <wx/crt.h>
31#include <wx/file.h>
32#include <wx/ffile.h>
33#include <wx/filename.h>
34
35#include <downgrade_target.h>
36
37#define ARG_TARGET "--target"
38#define ARG_FORCE "--force"
39#define ARG_DRY_RUN "--dry-run"
40#define ARG_REPORT_JSON "--report-json"
41#define ARG_REPORT "--report"
42#define ARG_VARIANT "--variant"
43#define ARG_DROP_APPROXIMATIONS "--drop-approximations"
44
46 COMMAND( "downgrade" )
47{
49 m_argParser.add_description( UTF8STDSTR( _( "Export a copy of the whole project readable by an older "
50 "KiCad version" ) ) );
51
52 m_argParser.add_argument( ARG_TARGET )
53 .default_value( std::string() )
54 .help( UTF8STDSTR(
55 _( "Target version name or id, e.g. \"KiCad 10.0\" or \"10.0\". Defaults to the newest." ) ) );
56
57 m_argParser.add_argument( ARG_FORCE )
58 .help( UTF8STDSTR( _( "Export even if some features must be dropped or approximated" ) ) )
59 .flag();
60
61 m_argParser.add_argument( ARG_DRY_RUN )
62 .help( UTF8STDSTR( _( "Print the compatibility report without writing anything" ) ) )
63 .flag();
64
66 .help( UTF8STDSTR(
67 _( "Omit features instead of approximating them; may remove drawing or electrical data" ) ) )
68 .flag();
69
70 m_argParser.add_argument( ARG_REPORT_JSON )
71 .default_value( std::string() )
72 .help( UTF8STDSTR( _( "Also write the compatibility report as JSON to this file" ) ) );
73
74 m_argParser.add_argument( ARG_REPORT )
75 .default_value( std::string() )
76 .help( UTF8STDSTR( _( "Also write the compatibility report as text to this file" ) ) );
77
78 m_argParser.add_argument( ARG_VARIANT )
79 .default_value( std::string() )
80 .help( UTF8STDSTR( _( "Flatten this variant into the export. Default is the base design." ) ) );
81}
82
83
84static const char* bucketName( DOWNGRADE_BUCKET aBucket )
85{
86 switch( aBucket )
87 {
88 case DOWNGRADE_BUCKET::KEEP: return "keep";
89 case DOWNGRADE_BUCKET::LOWER: return "lower";
90 case DOWNGRADE_BUCKET::DROP: return "drop";
91 case DOWNGRADE_BUCKET::BLOCK: return "block";
92 }
93
94 return "unknown";
95}
96
97
99{
100 if( !wxFile::Exists( m_argInput ) )
101 {
102 wxFprintf( stderr, _( "Project file does not exist or is not accessible\n" ) );
104 }
105
106 wxFileName proFn( m_argInput );
107 proFn.MakeAbsolute();
108
109 wxString projectDir = proFn.GetPath();
110 wxString projectName = proFn.GetName();
111
112 wxString targetName = wxString::FromUTF8( m_argParser.get<std::string>( ARG_TARGET ) );
113
114 if( targetName.IsEmpty() )
115 targetName = GetDowngradeTargets().front().m_name;
116
117 const DOWNGRADE_TARGET* target = FindDowngradeTarget( targetName );
118
119 if( !target )
120 {
121 wxFprintf( stderr, _( "Unknown target version '%s'. Valid targets: %s\n" ), targetName,
124 }
125
126 // Argument problems surface before the classification runs, not one rerun at a time.
127 if( !m_argParser.get<bool>( ARG_DRY_RUN ) && m_argOutput.IsEmpty() )
128 {
129 wxFprintf( stderr, _( "An output folder is required. Use --output.\n" ) );
131 }
132
133 wxString reportPath = wxString::FromUTF8( m_argParser.get<std::string>( ARG_REPORT ) );
134 wxString reportError;
135
136 if( !ValidateDowngradeReportPath( reportPath, reportError ) )
137 {
138 wxFprintf( stderr, wxS( "%s\n" ), reportError );
140 }
141
142 wxString jsonPath = wxString::FromUTF8( m_argParser.get<std::string>( ARG_REPORT_JSON ) );
143
144 if( !jsonPath.IsEmpty() )
145 {
146 wxFileName reportFile( jsonPath );
147 reportFile.MakeAbsolute();
148 jsonPath = reportFile.GetFullPath();
149 wxArrayString sources;
150 wxDir::GetAllFiles( projectDir, &sources );
151
152 for( const wxString& source : sources )
153 {
155 continue;
156
157 std::error_code error;
158 bool sameFile = std::filesystem::equivalent( jsonPath.ToStdWstring(), source.ToStdWstring(), error );
159
160 if( sameFile || reportFile.SameAs( wxFileName( source ) ) )
161 {
162 wxFprintf( stderr, _( "The report file must differ from the source project files.\n" ) );
164 }
165 }
166 }
167
169 wxString error;
170 bool dropInsteadOfApproximate = m_argParser.get<bool>( ARG_DROP_APPROXIMATIONS );
171 wxString variant = wxString::FromUTF8( m_argParser.get<std::string>( ARG_VARIANT ) );
172
173 if( !ClassifyProjectForDowngrade( aKiway, projectDir, projectName, targetName, report, error, nullptr,
174 dropInsteadOfApproximate, variant ) )
175 {
176 wxFprintf( stderr, wxT( "%s\n" ), error );
178 }
179
180 // The same printer the pcb and sch downgrade commands use, so the vocabulary matches.
181 report.Print( &CLI_REPORTER::GetInstance() );
182
183 if( !WriteDowngradeReport( report, targetName, reportPath, reportError ) )
184 {
185 wxFprintf( stderr, wxS( "%s\n" ), reportError );
187 }
188
189 if( !jsonPath.IsEmpty() )
190 {
191 nlohmann::json js;
192 js["target"] = std::string( target->m_name.ToUTF8() );
193 js["blocked"] = report.IsBlocked();
194 js["lossy"] = report.IsLossy();
195 js["drop_approximations"] = dropInsteadOfApproximate;
196 js["entries"] = nlohmann::json::array();
197
198 for( const COMPAT_ENTRY& entry : report.Entries() )
199 {
200 js["entries"].push_back( { { "category", bucketName( entry.m_bucket ) },
201 { "feature", std::string( entry.m_feature.ToUTF8() ) },
202 { "detail", std::string( entry.m_detail.ToUTF8() ) },
203 { "count", entry.m_count } } );
204 }
205
206 std::string text = js.dump( 2 ) + "\n";
207
208 if( !KIPLATFORM::IO::AtomicWriteFile( jsonPath, text.data(), text.size(), &error ) )
209 {
210 wxFprintf( stderr, _( "Could not write the JSON report to '%s'\n" ), jsonPath );
212 }
213 }
214
215 if( m_argParser.get<bool>( ARG_DRY_RUN ) )
216 return EXIT_CODES::OK;
217
218 if( report.IsBlocked() )
219 {
220 wxFprintf( stderr, _( "Cannot export: the project uses features the target cannot represent.\n" ) );
222 }
223
224 if( report.IsLossy() && !m_argParser.get<bool>( ARG_FORCE ) )
225 {
226 wxFprintf( stderr, _( "Export would lose data. Re-run with --force to export anyway.\n" ) );
228 }
229
230 wxFileName outDir( m_argOutput, wxEmptyString );
231 outDir.MakeAbsolute();
232
233 if( !ExportProjectForDowngrade( aKiway, projectDir, projectName, targetName, outDir.GetPath(), error, variant,
234 dropInsteadOfApproximate ) )
235 {
236 wxFprintf( stderr, wxT( "%s\n" ), error );
238 }
239
240 wxPrintf( _( "Exported to '%s'\n" ), outDir.GetPath() );
241 return EXIT_CODES::OK;
242}
argparse::ArgumentParser m_argParser
Definition command.h:113
COMMAND(const std::string &aName)
Define a new COMMAND instance.
Definition command.cpp:30
void addCommonArgs(bool aInput, bool aOutput, IO_TYPE aInputType, IO_TYPE aOutputType)
Set up the most common of args used across cli.
Definition command.cpp:135
wxString m_argOutput
Value of the output arg if configured.
Definition command.h:143
wxString m_argInput
Value of the common input arg if configured.
Definition command.h:138
static CLI_REPORTER & GetInstance()
Definition reporter.cpp:261
What an export to a given target will keep, approximate, drop, or block.
void Print(REPORTER *aReporter) const
bool IsLossy() const
True if anything is approximated or dropped. This is what triggers the lossy warning.
bool IsBlocked() const
True if some feature makes the target impossible. The user cannot export anyway.
const std::vector< COMPAT_ENTRY > & Entries() const
A minimalistic software bus for communications between various DLLs/DSOs (DSOs) within the same KiCad...
Definition kiway.h:348
#define ARG_VARIANT
Definition command.h:38
#define UTF8STDSTR(s)
Definition command.h:27
#define ARG_DRY_RUN
#define ARG_TARGET
#define ARG_FORCE
#define ARG_DROP_APPROXIMATIONS
#define ARG_REPORT
#define ARG_REPORT_JSON
static const char * bucketName(DOWNGRADE_BUCKET aBucket)
DOWNGRADE_BUCKET
What happens to a feature when we export to an older KiCad.
@ BLOCK
Cannot be represented at all, export to this target is not possible.
@ KEEP
Exists in the target, written unchanged.
@ LOWER
Approximated down to a simpler equivalent.
@ DROP
No equivalent, left out.
bool ValidateDowngradeReportPath(const wxString &aPath, wxString &aError)
A report destination that is a design or library file is a mistyped path, not a report.
bool WriteDowngradeReport(const COMPATIBILITY_REPORT &aReport, const wxString &aTarget, const wxString &aPath, wxString &aError)
Write the readable compatibility report, the same text the export dialog shows.
bool IsDowngradeDesignFile(const wxString &aPath)
Files the project export carries over.
const std::vector< DOWNGRADE_TARGET > & GetDowngradeTargets()
Supported downgrade targets, newest first.
const DOWNGRADE_TARGET * FindDowngradeTarget(const wxString &aNameOrId)
Match a user-supplied target string against name or stable id, case-insensitively.
wxString DowngradeTargetNames()
The valid target choices as one user-facing list, for error messages.
#define _(s)
std::string source
static const int ERR_ARGS
Definition exit_codes.h:31
static const int OK
Definition exit_codes.h:30
static const int ERR_INVALID_INPUT_FILE
Definition exit_codes.h:33
static const int ERR_UNKNOWN
Definition exit_codes.h:32
bool AtomicWriteFile(const wxString &aTargetPath, const void *aData, size_t aSize, wxString *aError=nullptr)
Writes aData to aTargetPath via a sibling temp file, fsyncs the data and directory,...
bool ExportProjectForDowngrade(KIWAY &aKiway, const wxString &aProjectDir, const wxString &aProjectName, const wxString &aTargetName, const wxString &aDestDir, wxString &aError, const wxString &aVariant, bool aDropInsteadOfApproximate)
Export a downgraded copy of the project into aDestDir.
bool ClassifyProjectForDowngrade(KIWAY &aKiway, const wxString &aProjectDir, const wxString &aProjectName, const wxString &aTargetName, COMPATIBILITY_REPORT &aReport, wxString &aError, std::vector< wxString > *aFoundVariants, bool aDropInsteadOfApproximate, const wxString &aVariant)
Run the board and schematic classification for a whole project without writing anything.
int doPerform(KIWAY &aKiway) override
The internal handler that should be overloaded to implement command specific processing and work.
One line in the compatibility report.
An older KiCad release we can export a project back to.
wxString m_name
User-facing name, e.g. "KiCad 10.0".